How To

Start with your idea right away.

How to use blokdots

blokdots is a simple software to programm hardware. To understand how that works just a few basic infos how its setup is.

The app is set up in two main windows, the Live View and the Project window.

Here is a typical setup. The Live View is the smaller one (left) and the Project window is the bigger one.

The Live View displays all hardware components that are currently connected to your board. From here you can also connect new ones, disconnect some others and most importantly, you can see the current values of sensors as well as manipulate the values of actutators. This is helpful for learning which component has which limits and what to use them for.

The Project displays the actual algorithm you want to create. Here your connections are built and the setup for your prototype is defined, basically the main window to build your protoypes.

How to set up hardware

First of all, you will need an Arduino Uno, a basic microcontroller used in many prototyping projects.

blokdots is intended to use the Grove components by Seeed Studio since they manage most of the wiring for you. To begin the Starter Kit for Arduino is suggested.

Of course you can also use regular components, but here you need to wire them up yourself. The pins are named the same as when using the Grove shield.

Put the Grove shield on top of your Arduino Uno, and plug it in to your computer, the correct firmware will automatically be uploaded to your board once started the software.

Just plug in the components to the grove shield. Digital components to slots marked with a "D", analog components to a slot marked with an "A". Some special PWM components just can connected to the slots 3, 5 and 6. Read the Live View Section for more infos on that.

See here where to connect your component and what their features are, if you are not certain.

How to use the Live View

The Live View shows you which components are currently connected to your board. When connecting an new component, click on "Setup new component". Select the component you want to connect, the software will help you find a suitable slot to plug it in.

For more advanced users you can also disable this wizard and select your slot directly. Just go into the Settings window and disable Simple Live View.

Once connected, you will see here the current values (if the component is an input) or manipulate the values of the output.

Clicking on the arrow even gives you more options, like a graph, showing the last 10 seconds of values, additional options or settings for your component.

Acutators allow it to be manipulated. E.g. this servo can adjust its angle.
Sensors only show their values.

To disconnect a component, simply hover over the top right corner of a slot and click on the appearing "x" to close the slot. Now you can reset a different component again.

How to build a project

Setup Components

To use a component into a project, click "use" either within the setup in your project window, or within the live view. Once set, you can now use your hardware to build connections.

Reconnecting Components

If you open an existing project, you can easily setup the components in the Live View by clicking the "Apply Project Slots" button. This way you do not have to set up each component over and over again when working on the same project again.

Connections

Overall there are two types of cards which can be selected via the Add Card button.

Trigger Cards ctrl+Space

Trigger Cards are the classic connection between two components. They are set up similar to the IFTTT (if this then that) manor, meaning your relations form simple sentences like "If one thing happens, then an other thing should react".

Simply click through the wizard until your final result is happening for one connection. There can be as many of these connections as you want. Also there is no limit on how many reactions happen onto the same kind of action.

Relation Cards ctrl+Shift+Space

Relation Cards are useful for direct controls. They allow you to map one value to another, e.g. to map the roation of a potentiometer to the rotation of a servo.

You can not only map components directly 1:1 but also shift the mapping by either dragging the sliders at the bottom or changing the values within the textural interface.

Find Cards cmd+F

If you are searching a connection, simply click in the upper search bar. Here you can filter cards on their title or components.

Run Project cmd+R

Once you want to test your project, click the "Play" button on the upper left. The code is getting compiled and your project will immediately start.

Should something not work, an error will occur and shown next to the Play button.

Change Names

For better structuring your project, you can rename the project itself, the IFTTT cards and components. Simply click on the name and start typing.

Save cmd+S / Open Projects cmd+O

To save your project hit the "Save" button and select a location. It will be saved as a .blokdots file.

The buttons right below "Run Project" allow to save, load and export.

How to export code cmd+E

When exporting a project into code, a .js file is generated. This file contains the exact code built using the app, but in plain javascript.

Here is an example of how it could look like:

// ---- Setup the board ----
const five = require("johnny-five");
const board = new five.Board();

// -- Setup vars
let led;
let button;

// ---- IFTTT ----

// Card 0
function card0Reaction() {
  led.off();
}

// Card 1
function card1Reaction() {
  led.blink();
  setTimeout(function() {
    led.stop().off();
  }, 5000);
}


// ---- Run ----
board.on('ready', function() {
  // -- Setup components
  led = new five.Led(3);
  button = new five.Button({
    pin: 2,
    holdtime: 1000
  });

  // -- Setup event listeners

  // Card 0
  var card0Counter = 0;
  button.on("down", function() {
    card0Counter++;
    if (card0Counter >= 3) {
      card0Counter = 0;
      card0Reaction();
    }
  });

  // Card 1
  var card1Counter = 0;
  button.on("hold", function() {
    card1Counter++;
    if (card1Counter >= 2) {
      card1Counter = 0;
      card1Reaction();
    }
  });
});

// ---- Stop ----
function stop() {
  // Remove event listeners
  if (led && led._events) {
    led.removeAllListeners();
  }
  if (button && button._events) {
    button.removeAllListeners();
  }
}

To be able to use it, you need to install Node js. When having it installed you can start using the script by opening the folder in your terminal and type the following:


$ cd your/project/folder

$ npm install johnny-five --save

$ node project-file.js

Now the project should run exactly the same way as using the blokdots app.

You can adjust the code here as you want using the Johnny-Five API or use other node modules to control a webinterface with your hardware.