Here you’ll find everything you need to know to create your best prototype.
Installation
macOS Version
After downloading simply drag and drop blokdots into you Application folder.
Windows Version
Double click on the "Blokdots-Setup.exe" to install blokdots.
Opening Dialog
We are still a fairly small Start-Up and the Windows version is quite new, so it is very likely that when you open the application for the first time, the Windows Smart Screen appears which looks like this:
Image from Webcatalog
If this dialog appears, please click on "more info" to reveal the developer information. You should see now something with "blokdots" in the app field and "Olivier Brückner" in the publisher field. Now click "run anyway" to start the app. Here you also can find a step-by-step video guide.
Port Recognition
It might be, that the Arduino board is not recognized by blokdots directly after its installation. We recommend to restart your computer after installing it.
Also when first plugin in an Arduino board, your computer intends to set up the device. Start blokdots after the initialization is done to guarantee the Arduino's port is available for blokdots to use.
Base Setup
Arduino
Supported Boards
Currently we support only Arduino boards. The boards we support are listed here:
Firmata
To be able to communicate with blokdots, the Arduino needs to be flashed with Firmata. Firmata is a special protocol that allows the Arduino to communicate with a computer. One you start blokdots and plug in your Arduino, blokdots flashes the board with the Firmata automatically, so usually you do not have ot worry about that. This is indicated by a smal green box at the top of the Live View.
To install Firmata without the blokdots software, open the Arduino IDE and go to File › Examples › Firmata › StandardFirmataPlus, and flash this on your board. It is the same file, if you are interested in the code.
Grove
We currently have decided to use the Grove components created by Seeed Studio, since they are very simple to use and do not require any wiring for the components.
The Beginner Kit has everything you need to start right away. A Seeeduino Lotus board with Grove connectors, 10 components, Grove cables, and a USB cable. It costs around 20 US$ (price subject to change due to external distributor).
You can order it here.
Disclaimer: We are currently about to implement all components featured in the kit, which means not every component is working yet with blokdots that comes with it. We already have the following components included: Button, Rotary Potentiometer, Brightness/Light, Sound, LED, Buzzer, Accelerometer, and Air Pressure. Please bear with us until we have the missing components included as well, thank you!
Grove Shield
Of course, you can also connect the Grove Shield for Arduino as displayed below:
Simply put the shield on your Arduino and plug in the components into the slots.
Set the little switch at ”VCC” (next to the analog slots) to ”5V” to allow every component to function properly.
Using Own Components
blokdots does, however, also work without the Grove shield – You can of course use your regular components as well. The name of the Arudino pins hereby resemble the Grove slots. E.g. What would have been Slot D4 is pin 4 on the Arduino board.
Slot Types
In general there are four slot types that are currently supported: digital, analog, pwm and I2C.
- digital — the basic setup. It only can communicate with “on” or “off” in both directions, in and out.
- analog — analog slots are only able to read values (aka in). In comparison to the digital slot is able to read values between
0and1023, a relatively wide range to get detailed infos from your sensors. - pwm — this is a technology to transform digital values cleverly into an output that behaves as if it is “analog”. This enables some components to have a more granular output setting. Unfortunately on the Grove Shield, these slots are not marked. They do however still exist! E.g. on an Arduino Uno these slots are: D3, D5, and D6.
- I2C — this is a serial communication connection that allows for more complex data handling. Only very very few components actually use this connection. You can think of it as an USB device that you simply plug in to your computer. That also is the reason why you do not need to specify which of the different I2C slots on your Arduino you are using. You can also split this slot with an adapter to plug in as many I2C devices as you want.
You can only plug in a component into the relevant fitting slot. See in the Hardware Components section which component is set for which type. Also the Wizard helps you to select the right available slot for your component when using blokdots.
Live View
blokdots has two windows: The Live View and the Project View. Let’s focus on the Live View first. The live view is the control center for you Arduino – it should always reflect the state that your Arduino is in right now. This means when you plug in a new components, you need to tell blokdots about it, so that it can control it.
Connecting A Component
The main part of the Live View is a list of the slots of your Arduino. To tell blokdots that you plugged in a new component, click on the appropriate slot. This will expand a list of all the components that are compatible with this slot. Select the one you plugged in and you are good to go.
To remove a component from the Live View once you unplug it, move your mouse over the appropriate slot. A “×” symbol appears in the top right corner of the slot. Click the symbol to remove the component.
Wizard
It can be confusing the figure out which kind of component can be plugged into which kind of slot and where that slot is on your Arduino. blokdots solves this problem for your, with the setup Wizard.
Click the “Connect A New Component” button on the top of the Live View to open the Wizard. On the left side of the wizard there is a scrollable list of the components that are available – pick the one you want to connect. Now blokdots will recommend you a free slot to plug your component into and show you where that slot is on your board in the small map on the right side. If you are happy with this slot, go ahead and click “Set Component”, after you plugged it in. Otherwise you can click on the name of the slot displayed in the middle of the Wizard to get a list of all other slots that would be suitable.
Displaying The Current Value
Once set up, the slot displays the current value of the component. For a sensor it simply shows its reading value, for an actuator you are able to manipulate the value as well and directly see the feedback on the hardware component.
Next to the actual, the ”current value”, you are able to select the unit in which the value should be displayed. This depends on the component you have selected. While for a Temperature Sensor °C might make more sense, for a button simply ”on” and ”off” will do.
Live Graph & Component Options
After plugging in and setting up a component, you can click the small downward facing arrow on the right side of the slot to expand its detail view. What exactly is shown depends on the component, but usually you’ll find a Live Graph, giving you a visual representation of the component’s values of the last ten seconds, and in a second tab some options. With the options you can configure the exact behavior of the component. Most options show a little “i” symbol next to their title. Move your pointer over it to see a tooltip describe exactly what the option does.
Projects
blokdots’ second window is the Project View. This is where your actually build your prototype and can create your programs.
Using a Component in a Project
You need to tell blokdots which of the components that are currently connected and set up in the Live View you want to use in your project.
You do this in the Project View’s Project Components section on the left side of the window. There you see a list of all your Arduino’s slots and a preview of the components which are set up. To use a component in your project, click the “use” button on the right side of the slot. The component now become active. If you remove it from the Live View, it still is active in the Project View, because blokdots knows your project will only work if the component is set up.
If you do not need a component in your project any more you can remove it: move your mouse over the appropriate slot. A “×” symbol appears in the top right corner of the slot. Click the symbol to remove the component.
You can also give a component a custom name, for example if you use multiple components if of the same type in a project. Simply click on the name of the component in the Project Components section and type in the custom name.
Opening a Project
blokdots works like any other macOS program for editing files, which means you can save and open your project as a document. When you open a previously saved project, the Project View will display the project. The Live View will not change, because it always displays the actual current state of your Arduino, not a “saved” state.
That means it can happen that you open a project that uses specific components, which are not set up in the Live View right now. To run the project you have to make sure to connect the components which you can see in the project’s Project Components section to your Arduino and set them up in the Live View. To automatically set up all the project’s slots at once, click the button showing a symbol of two arrows in the top left corner of the Project View.
Card Types
You can create a program for your protoype by adding and configuring cards. There are two types of cards in blokdots: “If This Then That” cards and “Mapping” cards.
A button in the Project Window’s main area lets you easily select one of these two.
If This Then That Cards
If This Then That cards are the most simple type of cards: They wait for somthing to happen, then trigger an action. To add a new card of this type to your project, press the “If … then …” button in the top left corner of the cards section in the Project View.
Now fill out the sentence to configure your card: Fist pick a component that you want to trigger the action and specify the circumstances. Then select a component to perform the action and specify its behaviour. Every one of the colored boxes in the card is a dropdown menu, giving you several options to choose from.
Mapping Cards
Mapping cards describe a continous relationship between to components. This means you can directly map the values from an in-component to the value of an out-component. For example a the position of a Potentiometer can control the brightness of an LED, or the value of a Temperature Sensor can control the position of a Servo Motor.
The relationship between the two components you select is linear, but you can control the minimum and maximum value of both components, allowing you to create flexible mappings.
Working with Cards
Deleting a Card
If you don’t need a card anymore, you can click the “×” symbol in the right corner of its header to delete it.
Naming Cards
By default the cards you create a just numbered, but you can give them more helpful names. Simpley click on the name of the card in the card’s header and enter the new name.
Disabling Cards
If you want to run your project without a specific card you can disable it temporarily. Click the toggle switch on the right side of the card’s header to disable or enable it.
Filtering Cards
When you have many cards it can be helpful to use the filter bar to find the one you are looking for. You find it on the top of the cards section in the Project View. When typing in your query, blokdots will filter the cards below. You can filter by the name of a card, the name of a component or the value of a parameter.
Running Your Project
To run your project, press the big play button in the top left corner of the Project View. If there is an error in your project, it will be displayed up there as well. When you change your project while it is running, a small green indicator appears. Changes will only be effective, after you stop and restart your project.
Code Export
This feature is still experimental, some elements might not work as expected.
If you want to export your project to JavaScript, go to File › Export to Code and pick a location. It can be helpful to give your project components and cards custom names before exporting, to make the code more easily readable.
blokdots will create a folder containing three files:
- your project as javascript file
- a
package.json - a
README.md
The javascript file contains your project in a executable format. The README.md file contains a brief explanation on how to use the generated folder and where to connect your components to. It is written in markdown. The package.json contains all the necessary information to continue working on your project.
JavaScript File
Here is an example of how this code would look like:
// ---- Setup the board ----
var five = require("johnny-five");
var board = new five.Board();
// -- Setup vars
var led;
// ---- IFTTT ----
// Project Start Signal
function ProjectStartSignalReaction() {
led.blink();
setTimeout(function() {
led.stop().off()
}, 5000)
}
// ---- Run ----
board.on('ready', function() {
// -- Setup components
led = new five.Led(2);
// -- Run reaction when project starts
// Project Start Signal
ProjectStartSignalReaction()
});
// ---- Stop ----
function stop() {
// Remove event listeners
if (led && led._events) {
led.removeAllListeners();
}
}We are using Johnny Five to communicate with the Arduino. If you want to dive deeper into the generated JavaScript code, we suggest you have a look at its API to adjust the code to your needs.
Addtional Packages
When exporting your project and using virtual components, like the Timer, you will need include an additional npm package to your project, next to Johnny Five. When exporting a project from within the app, this will already be included in the package.json.
Using it in your project would look like this:
const components = require("@blokdots/components");
let timer = new components.Timer(0);
timer.on("change", (value) => {
console.log(value);
});
timer.start();Installing the Exported Project
Make sure you have node.js installed.
Open the exported folder in your Terminal (macOS) or cmd.exe (Windows). Then run:
npm installThis will install all the required dependencies for your project to run.
Now you can start the project by running:
npm startThe project should now work as in the blokdots software.
Hidden Features
Display Current Value of Sensor
To display the current value of a sensor, for example on an LCD Display, you need to set the “if” part of the card to “is changing”, then type in {{value}} in a text field, to get it displayed.
Activate Beta Features
To activate features that are currently in Beta, go to blokdots › Preferences….
Components
Overview
Counter
Metronome
Project
Signal Tower
Timer
Accelerometer
Air Pressure Sensor
Brightness Sensor
Button
CO2 Sensor
Encoder
Moisture Sensor
Motion Sensor
Potentiometer
Slide Potentiometer
Sound Sensor
Sunlight Sensor
Temperature Sensor
Tilt Switch
Touch Button
Water Sensor
Buzzer
LCD Display
LED
Relay
Servo Motor
Vibration Motor
Figma
ProtoPie Connect
Socket.IO Server
CounterBeta
virtualMetronomeBeta
virtualProject
virtualSignal TowerBeta
virtualTimerBeta
virtualAccelerometer
I2CAir Pressure Sensor
I2CBrightness Sensor
analogButton
digitalCO2 Sensor
digitalThis component occupies two consecutive slots.
Encoder
digitalThis component occupies two consecutive slots.
Moisture Sensor
analogMotion Sensor
digitalPotentiometer
analogSlide Potentiometer
analogSound Sensor
analogSunlight Sensor
I2CTemperature Sensor
analogTilt Switch
digitalTouch Button
digitalWater Sensor
digitalBuzzer
digitalLCD Display
I2CLED
digitalLEDs can function as both, digital outputs (on/off) and analog outputs (adaptive brightness) if connected to a PWM slot.
Relay
digitalServo Motor
pwmVibration Motor
digitalFigmaBeta
virtualThis component requires the blokdots Figma plugin and the Figma desktop app. This component does not yet support code export.
ProtoPie ConnectBeta
virtualThis component does not yet support code export. Also, it requires ProtoPie Connect.
Socket.IO ServerBeta
virtualIntegrations
Figma Plugin
Our Figma integration lets you manipulate different properties of layers in Figma right from your Arduino prototype.
Setup
First you need to install our Figma plugin: Get it here. Then you need to enable the Figma integration in blokdots, because it is still in Beta: Go to blokdots › Preferences… and enable it.
No you can run the plugin in Figma – it only works with the desktop application of Figma, not when you are using Figma in your browser! Make sure to already have blokdots running the background. Figma and blokdots will now connect and you are good to go.
Expose Your Layers
You need to tell blokdots, which layers from your Figma document you want to manipulate. To do that select a layer in Figma, then click the “Expose current selection to blokdots” button in the plugin. If you close the plugin, it remembers which layers were exposed when you open it again.
If This Then That card
In blokdots you can now add an If This Then That card and select Figma as the “then” component. In the black dropdown menu, select the layer you want to manipulate. With regular layers you can rotate them, set the background color, set the opacity and set or change the position or size. For text layers you can also set the color of the text and the content of the text.
To display the value of a sensor in a text layer, set the condition of the “if” component to “is changing”, then select a text layer and the action “set text”. If you now type {{value}} into the text field, your layer in Figma will display the value of the component.
Mapping Card
You can also add a Mapping card in blokdots, select Figma as the “onto” component, and then select a layer from the black dropdown menu. You can map the value of a component onto a layer’s size, position, opacity and color.
Run Your Project
When running your project make sure the Figma plugin is also running and blokdots and Figma are connected. If the plugin doesn’t connect it can help to close it and run it again.
ProtoPie Integration
Our ProtoPie integration enables you to control your ProtoPie prototype with your blokdots prototype and in the other direction as well!
This only works with ProtoPie Connect at the moment, an enterprise feature for ProtoPie.
How the ProtoPie connection works
In order to let blokdots talk to ProtoPie we’re making use of the messaging feature built into ProtoPie via the Send / Receive triggers. It’s a nifty feature that lets different prototypes talk to each other. With the help of ProtoPie Connect we can tap into the messaging system and exchange messages between blokdots and ProtoPie.
If you want to play around a little more with it, take a look at the ProtoPie Connect component in blokdots. The orange message field in blokdots corresponds to the Message field in the Send/Receive trigger in ProtoPie.
When you use ProtoPie Connect for the Then action of any input capable hardware component, the integration will send the message and will also try to send a corresponding value with the message. I.e. if you use the ProtoPie Connect component with a potentiometer you will get the values from 0 to 1023 that you receive from the potentiometer attached to the message. You don’t need to do anything with the value in ProtoPie, but you can.
For the return route – sending messages from ProtoPie to blokdots – you can use messages to trigger behavior on the If…then cards or if you want to use a value from ProtoPie to fade an LED in and out, you can use a Map…onto card to map the incoming value to the hardware component in blokdots.
Create your own interactions
You can experiment with what’s possible by creating your own messages to be send and received. Best to keep the messages short, i.e. “ToggleLED” is better than “Toggle the LED light on or off”.
The ProtoPie live slot
Once you selected the ProtoPie Connect component component in the Live View you will see the slot shown above. If blokdots is able to connect to the ProtoPie Connect software—so if the software is up and running—the little connection indicator at the bottom left of the ProtoPie icon should turn green.
If your ProtoPie Connect server should not be at the default location, e.g., it is not running on your computer but on someone else's, then you can simply change the address in the field filled with http://localhost:9981. Usually, this address should work with your setup.
Above the text field and if expanded, you can see the last communication between ProtoPie and blokdots. It behaves similarly to the connection between Signal Tower components.
ProtoPie to blokdots
In ProtoPie Studio:
- Configure a trigger and use the “Send” response.
- Select “ProtoPie Studio" as the channel.
- Enter the message to be sent.
- Optional: Choose a value to be sent with the message
In blokdots:
- Create a new Card and select the ProtoPie Connect component. It should be set to "receiving".
- Enter the message in the orange input field. It needs to match the message configured in ProtoPie exactly.
- Define the Then reaction in the card by adding a component and selecting what it should do.
To use the message value as a string, you can access it via {{value}} in a text input field, e.g. when you want to send a message from ProtoPie to an LCD module, it would look like this ↑.
To use numerical values sent with messages, use a Mapping Card to set, e.g., the brightness of an LED or the movement angle of a servo motor.
blokdots to ProtoPie
In blokdots:
- Create a new card with an input component, i.e. a button, potentiometer or another sensor you have available
- Use the ProtoPie Connect component for the Then reaction
- Enter the message to be sent in the orange input field
In ProtoPie Studio:
- Use “Receive” as a new trigger
- Select “ProtoPie Studio” as the channel
- Enter the message exactly as configured in blokdots
- 💡 Tip: Create a variable in your Pie and use the Assign to Variable feature. Blokdots will try to attach a value for your input component and the value will then be assigned to the variable in your Pie.
- Continue with defining the triggered responses in ProtoPie Studio
Socket.IO Integration
Our Socket.IO integration creates a Socket.IO server, so that you can use an existing Socket.IO client or create your own to connect to blokdots and exchange messages. It allows you to read sensor data or control hardware outputs from whatever other tool or application you have in mind.
We are using Socket.IO v4, but clients with a minimum of v2 should work.
We only support the
websockettransport.
Message format
When you listen for a message from our server or want to send a message to blokdots, the first argument of the message should always be blokdots, so that we know that this message is intended for us. The second parameter in the message is an object with two parameters msg and val.
{
msg: "poti",
val: 10
}Usage in blokdots
The msg parameter is the same as the text in the message field of the Socket.IO server component used in your project. The val parameter represents the value attached to the message. In the example above, we have are using a potentiometer with an If-Then card and the sentence "If Potentiometer changes, then Socket.IO Server should send poti". The latest value from the potentiometer will be automatically attached to val.
If you want to display a string value you've received from a message, you can enter {{value}} into the textfield of a Then-Card, i.e. to display the incoming message on an LCD display.
If you're developing in JavaScript, the call to send a message to blokdots could look like this:
socket.volatile.emit("blokdots", {msg: "SetBrightness", val: 50});We recommend the use of volatile, but it is not required.
In order to listen to messages from blokdots, you can create an event handler like this:
socket.on("blokdots", (data) => {
if(data.msg && data.msg === "buttonPressed") {
// what shall we do when the button was pressed?
}
});Example blokdots project
Here you can download an example project that works together with the Grove Beginner Kit. It will send a Socket.IO message when the button is pressed or the potentiometer is changed. When ever the server receives a count message, we will confirm by letting the LED blink.
Node.js client
We provide a simple Socket.IO client in a Node.js script to connect with blokdots. You can use this as a base for your own experiments.
TouchDesigner
To connect TouchDesigner with blokdots, you can make use of the SocketIO DAT. Here you can download an example TouchDesigner project that has a pipline set up from blokdots to a constant CHOP. It uses the potentiometer's values from the example project above.
Privacy and Tracking
When you start blokdots for the first time, you are asked if you are okay with us collecting some usage data through the app. Unless you explicitly set the checkmark and opt in no data is collected whatsoever. If you change your mind you can always update the setting in the preference panel of blokdots.
How We Track
We use Mixpanel to collect usage data. The data is tied to an anonymized user id (there is no way for us to find out who you are based on the data we receive).
What We Track and Why
We believe that getting some information about how our users actually use blokdots will help us improve the app and make sure we deliver the most value to our users. We greatly appreciate it if you choose to allow us to collect some usage data.
We make sure to never collect any data that lets us identify you or the specific content of your project.
If you allow us to collect your usage data, this is what we track:
- That you use the app: We compile a number of monthly active users.
- Which version of the app you use: We keep track of which versions of the app are actually in use, because when we push bugfixes we need to know which versions of the app to target.
- That you added a card: We use this as a general indicator for how active our users are.
- That you ran a prototype: To understand how users use the app, we want to collect some information about the projects that are created. We do not track the name of any project or card. We only track how many cards are in a project and which components are used (see below).
- Which components are used: We would like to add more components to blokdots, to make it more useful to more users. In order to know which direction we should go in, it is important for us which components are actual being used in projects (and how often). Which components are used in a project is only tracked when you run the prototype.
- That you used the export code function: We want to know how often this feature is being used so that we can decide how important it actually is for our users.
If you have any questions about this, feel free to reach out to our support contact provided below.
If you have any questions or are in need of product support, don’t hesitate to reach out.moc.stodkolb@troppus