Documentation

0. Before you read this
We will try to keep this section up to date, and as correct as we can. Please, if you see any error (even in spelling) let us know it. You can post a comment here, make a mention (@juliandasilvag) by Twitter, or post into the forum's Forum. If you are an alpha tester or a Kickstarter backer, you already have Julián's e-mail. In general, the information on this page corresponds to the last miniBloq version. And you are invited to join the forum, of course. If you want to see documentation about the blocks, please visit this page. Thanks!


1. Other documents
There are other documents about miniBloq, in different languages, available for download. Here is a (useful) list of them:

2. What is miniBloq?
miniBloq is a graphical programming environment for Arduino™, Multiplo, physical computing devices and robots. One of it's main goals is to bring closer physical computing and robotic platforms to primary schools, kids and beginners. If you want to see a short intro, you can take a look to the video used for the Kickstarter campaign.


3. Getting started
3.1. miniBloq includes the device drivers for your hardware
Regardless of your operating system, some boards may need drivers. miniBloq includes all the necessary drivers for the supported hardware in a subdirectory (once installed, please see below to learn how to install in the different operating systems). Inside the directory where you installed miniBloq, you can find the drivers in the drivers subdirectory (for example: in a typical Windows installation the full path to the drivers will be C:\Program Files (x86)\miniBloq.v0.8x\drivers). Each board in turn has its own subdirectory there.

3.2. Windows
To run miniBloq under Windows, you have to easy options:
  • The easiest way of running miniBloq under Windows, is by downloading the Windows installer version. Then double click it (in Windows 7 the operating system will ask you to authorize it to run, so please just say "yes") and follow the steps. By default, miniBloq will be installed in C:\Program Files (x86)\miniBloq.v0.8x (this is the default path in Windows 7, which may be a bit different for previous versions of Windows). Then you have to run miniBloq.exe from one of the shortcuts created by the installer both in the Start Menu or in the desktop.
The only extra software you may need to install under Windows, are the drivers for the specific boards you want to program (DuinoBot, Seeeduino, Arduino™...). Every board may come with it's own driver installation instructions. For a list of supported boards, please read the section Supported hardware below (miniBloq also includes the drivers for most of the supported hardware in the drivers directory). There are some known issues, as you can read here (recommended). One more thing: some antivirus software may cause problems when installing miniBloq.

3.3. GNU/Linux
Since version v0.81.Beta.UP2, miniBloq runs natively in different GNU/Linux flavors. It was designed as an all-in-one package, so in principle, you don't need to install any dependencies. So, installing miniBloq under GNU/Linux is easy, just follow these steps:

1) Donwload the multiple-OS Minibloq version (zip file).
2) Uncompress it in the place you want (in Ubuntu, you can do this by right-clicking on the zip file, and choosing the "Open With Archive Manager" menu option.
3) Go to the directory where you decompressed miniBloq, and select the MinibloqRun.sh, right click it and choose Properties from the contextual menu.
4) Go to the Permissions tab in the Properties window and set the Allow executing file as program checkbox:
5) Now double-click on MinibloqRun.sh (or run it from a console). miniBloq will take some time, but then it will run:
The multiple-OS version have all the necessary files to run natively both under GNU/Linux AND under Windows. Please refer to the Versions, changelog and known issues page to see the differences with the Windows version. The native GNU/Linux version was mainly the work of Juan Pizarro, from doingIT, an open source company from Chile. Thanks Juan! Finally, if for some reason, you still prefer to run miniBloq under GNU/Linux with Wine, here you will find additional information.

3.4. OLPC XO
miniBloq may run on OLPC XO computers using the same steps descibed in the previous GNU/Linux section, but only with the GNOME interface on the OLPC XO:

Here are the steps to install miniBloq in the OLPC XO:

1) Switch to the GNOME interface (NOTE: Not all the OLPC XO computers come with this software installed from factory, please see The OLPC Wiki for further information).
2) Follow the steps described in the GNU/Linux (previous) section.
3) If you have problems with missing libraries, please take a look to this post: http://tdrobotica.co/arduino/350-minibloq-olpc (Spanish).

IMPORTANT NOTE: Please take into account that we did not test the native GNU/Linux version with the OLPC XO, but the Windows-based miniBloq version using Wine. We were involved in a project using XOs during the year 2011, but sadly we do not longer have the hardware. So feedback about running miniBloq GNU/Linux  native version on these amazing computers will be very welcome (you can post in this forum, for example). If for some reason, you prefer to run miniBloq on the OLPC XO with Wine, here you will find additional information.

3.5. Mac OS X
Ulises Mendoza, from Spain, has been working on a Wineskin wrapper for miniBloq. Thanks Ulises! Please read this page to find the details to run miniBloq with this wrapper.


4. Examples and Tutorials
miniBloq includes a bunch of examples. From the v0.8.Alpha onwards, there is an Examples submenu in the File menu. But the examples will be updated and enriched with videos, images, circuits, etc., in the Tutorials and Examples page. It may be worth to take a look there often, because it's updated often...


5. Features
5.1. Already implemented features
miniBloq is under development. These are the implemented features in the last working version:
  • Easy: Just a few clicks and your first program is running.
  • Real-time code generator: It creates the code while you are adding blocks or modifying param values, showing the code in a syntax colored window. This way, miniBloq facilitates the transition to text-based programming.
  • Real time error checking.
  • Basic drag& drop with autopan.
  • Advanced interface: Zoom, cut and paste, dockable windows, and keyboard navigation are just some of the miniBloq GUI's features. And there is more...
  • Embedded terminal: There is an embedded terminal that lets you send and receive data to your board through serial/USB ports.
  • All-in-one-ready-to-use-solution: This is "batteries included software". The package includes everything to start working.
  • Portable: It does not requires installation (except for the drivers required for specific boards, like Arduino™). It can run from a pen drive too. Oh, and it runs completely off-line, all in your own computer. More: You can have parallel copies of miniBloq, even with different settings running in the same computer.
  • Fast: I'ts a native application, compiled with C++ (gcc), using wxWidgets. For this reason, miniBloq is suitable for low end computers and netbooks. And, it also includes precompiled cores, it builds and downloads your programs really fast. Try it!
  • Modular and expandable: The user can easily create it's own new blocks.
  • Internationalization: The current version is available in English and Spanish, but the user and the community can contribute with new translations, using the open source Poedit tool.
Here is a small video showing some of these features:


And here are two more videos (showing real time error-checking in the variables subsystem, etc.):




5.2. Comming soon features
  • Free and ¡with sources!: The program will be available for free, in its full version. No fees for advanced features or the like. Just download and start using it. In addition, the full source code will be available too. The license? Something called RMPL (RobotGroup-Multiplo-Pacifist-License). This license is basically a MIT license, but with a restriction that bans military projects. More on this below. Here is also the Spanish version of this license.
  • Easy integration with new hardware: Adding support for new platforms and boards will be straightforward. This may be not a feature for beginners, but it will not be so difficult anyway. Even different compilers and languages could be added.

5.3. Future
We have a lot of ideas for the future of miniBloq. So please stay connected! Also, you can take a look to our last post about the roadmap.


6. GUI elements
Here, the main GUI (Graphics User Interface) elements are described and named. The names used here are the ones that you will find across the project's documentation.

6.1. Basic GUI elements
Here is a screenshoot of miniBloq's main window, as seen when it starts the first time:


6.2. Menu and Quick toolbar
Both the Main menu and the quick toolbar are dockable (and can be turned into floating windows). The quick tool bar can even be hidden (Alt + Q or View->Quick toolbar menu)


In future software versions, toolbar's buttons may become customizable, but now, we made our best to design a minimalistic GUI as functional as possible.

6.3. Hardware
In this window you can select both the type of board you are using, and the port to which that board is connected. It shows a simplified board image, with labels showing where to connect some external hardware (like certain kinds of sensors, motors, etc.). We are working to make these connections user-configurable in the future, but most of them are fixed in the current software version. This window is dockable and to hide or show it, you can both use the View->Hardware menu or press Alt + H:

A word about selecting the right communication port for your hardware:
  • Windows: Except for some devices (like the DuinoBot.v1.x.HID, for which miniBloq automatically sets the correct port), you will need to select a COM port from the Port combo box manually. This is the same process for most software environments (such as the Arduino IDE), but if you are not sure which COM to select, a small tip you can do is this: unplug your hardware for a few seconds, and see which ports are listed (by pressing the small yellow arrow in the Port combobox). Then plug the hardware again. Now take a look to the listed ports, and the one that was not present before is (most probably) the one belonging to your board.
  • GNU/Linux: The above described process works the same way for GNU/Linux. But there is a small problem: when running in GNU/Linux, you will probably see a lot of possible ports to select. Some example names under Ubuntu are: Arduino Mega 2560 is in general listed as /dev/ttyACM0 and FTDI based boards (such as the Seeeduino Mega 1280) are listed as /dev/ttyUSB0.

6.4. Component Editor
A program in miniBloq is called a Component (more on this soon...). The Component Editor is where you make your program. You can add blocks using the Action pickers and parameters with the contextual pickers. The Component Editor features zoom (with the mouse wheel, the Zoom menu or with the keyboard -please see the shortcuts section below-), cut & paste (using the Edit menu, the mouse right button or with the keyboard), scroll and drag & drop. Also, it has an automatic indent system so programs always look indented:

6.5. Actions picker
The Actions picker is the only picker that can be always seen. This is because no matter which is the current block (the current block is the one marked with a red square in the Component Editor), you can always add an action block.  In the future we plan to make the actions picker a dockable window (and possible hidden, like the contextual pickers). The blocks loaded into the Actions picker depends on the selected hardware. Different boards may have different action blocks. The orange blocks are flow control blocks.



6.6. Contextual pickers
In miniBloq, there is a picker for each data type. This way, when you will add a param to a block, miniBloq only shows the blocks that can fit there, based on the param's data type. This is done displaying what we call contextual pickers, and helps to not annoy the user with a lot of blocks (most of which make non-sense for the param the user is trying to add). For example, here is the "number" picker:


All the blocks in the number picker return a number. In the previous image, the first line (violet) contains getter blocks. The getters return values from some special functions or from instances (or objects).  The blocks in the second line (green) are constants.  The following blocks (gray) are operations. Inside this gray zone, the blocks are also arranged, as can be seen. The last line (white / light gray) contains sensor blocks. These are in fact getters, but we decided to separate them to ease to find them. In fact, the whole arrangement is a bit arbitrary (for example, the "random getter" (the dice) could be put among the math "gray" blocks), and may change in the future. But right now, it works. Here is the bool picker:


6.7. Properties
The properties window lets the user to configure miniBloq. Currently, it only allows to select by hand the language of the IDE, from the list of installed language packages. But in the future, it will let to configure a lot of things:
The properties window is dockable and can be shown/hidden with Alt + P or View->Properties menu. It's important to note that miniBloq features autodetection of the operating system's language, but it's also possible to select a different language by hand. One nice feature is that it's not necessary to restart the application when the language is changed. This post has more information about internationalization.


6.8. Messages
The message window has two zones: one dedicated to the text messages themselves, and a progress bar. The green text represents commands generated/executed by miniBloq (like a call to a compiler) and their respective outputs (when succesful). Blue text shows messages that miniBloq shows to the user (most of the time to show some kind of process progress). Red text are errors. Some times, miniBloq's parser can't detect an error message from some external tools output, so it may show error messages in green too (we are improving this):
The messages window is dockable and can be shown/hidden with Alt + M or View->Messages menu.


6.9. Terminal
To show the terminal, please go to the menu View->Terminal or press Alt + T. The port used will be the one selected on the Hardware window, and it will not be opened until you press the terminal's Open button. If you are using another program that has to access the port, you will need to close the terminal window (which automatically will release the port) or press the Close button (and in this case, the port will be released without closing the terminal window). miniBloq automatically closes the port when it has to deploy a new hex file to the board (ie. when the Run button is pressed).
This terminal features zoom (by now, it only works by holding the Ctrl key while moving the mouse wheel). And you can send text as well as receive. The terminal has two views: Single (default) and Split. The only difference is that in the Split view, the sent characters appear in a different text box. Both in the Single and in the Split views, received text will be shown in green, while sent text will be in blue (these colors will probably be user configurable in the future).

6.10. Generated code viewer
miniBloq has a fun and useful feature: it generates code in real time. If you open the "Generated code viewer" (with the menu View->Generated code or just pressing Alt + G), you will see the following (dockable) window:
Every change you made in the Component Editor is inmediately reflected on the Code Viewer. Green dots will appear on the right margin, between the first and the last modified lines (this behavior may change in the future, but by now it helps to easily see the changes in the code). The generated code can be copied, and there is even a context menu (in English, because that menu has not been internationalized by now). The generated code can also be found easily: go to the menu Component->Open folder (or press Ctrl + D). It will open the component's folder. Inside that folder there is a subdirectory called: ComponentName_Files. Inside it you will find all the code and header files, along with the final (ie, hex in Arduino-compatible boards) and other intermediate files in the output subdirectory.

6.11. Help and Resource Center
In the current version, the Help and Resource Center is not finished. It only contains the credits, the license, and some links to miniBloq's website and online documentation (and examples):

7. Blocks
7.1. Complete blocks description
There are blocks that are included in miniBloq's official distribution. But the blocks can be added, modified or deleted by users. We will improve the way to add and edit blocks in future miniBloq releases. For a detailed description of the blocks currently deployed with miniBloq, please see the Blocks page.

7.2. A comment about sensor blocks
miniBloq has to be simple. As simple as possible. There are a lot of sensors supported by the environment, but most of them can be read with the AnalogRead or the IOPin getter (equivalent to digitalRead()) blocks:
But when a sensor requires specialized code, there is a sensor block in the appropiate picker:

7.3. Analog values
All the values in relation with analog devices have (in general) a range from 0.0 to 100.0 (always in floating point). Here are some examples:
  • The PWM (or AnalogWrite) block receives a parameter between 0.0 and 100.0 to specify the duty cycle.
  • The Motor block receives a parameter between -100.0 and +100.0 to specify the speed (in fact, it's a duty cycle for a PWM signal). The sign determines the direction of rotation.
  • All the analog sensors (except some specific sensors, like the rangers which work in metric units) return a value between 0.0 and 100.0.
This aproach has it's pros and cons, but we decided to implement it this way for some important reasons. Here are some of them:
  • It's more hardware independent. You don't need to worry about the resolution of the analog to digital converter (ADC), or about a PWM's resolution either. miniBloq aims to be a multihardware IDE, so this will let the user to write more portable code.
  • In general, this results in more compact code when the program has to use an analog input value to set an analog output:
  • We think the code is clearer, since you can think in the concept of a percentage, rather on a power of 2 (like the ranges 0 to 1024, or 0 to 255).

8. Features to facilitate programming
8.1. Real time error checking
miniBloq verifies most errors in real time, marking them with red. Here are the cases detected by the environment:

Incomplete parameters
When a new block is added, if it has parameters, its add-param button will be shown in red until a param is added:

Invalid variable names
miniBloq validates variable names while they are being written (in real time). So if the variable name is invalid, the environment marks it in red:
By other side, invalid chars can not even be typed.

Repeated variable names
miniBloq also detects when a variable name is repeated:
Deleted variables
If you declare a variable and then add setters or getters for that variable, and finally you delete the declaration, miniBloq will detect the missing declaration, marking in red all the ocurrences of that variable name:

Wrong formatted numbers
Although non valid chars can't be typed in numeric fields, it's still possible to write a wrong formatted number. miniBloq will show it in red:
Other errors
There are errors that are implicity prevented with miniBloq. For example, it's not possible for the user to confuse the operator "=" (assignment) with the operator "==" (comparison), since the environment will generate the right code automatically. Other common errors, like forgetting a ";" are not possible either. Due to the contextual pickers, it's also imposible for the user to add wrong data type parameters to a block. Finally, upper and lower case errors are also prevented automatically, thanks to the automatic variable name management (see next section).

8.2. Automatic variable name management
This is a very important feature, since it prevents a lot of potential syntactic errors, wich is a main goal in graphical programming. miniBloq detects automatically when a variable name is changed by the user (in a declaration), and updates all the ocurrences (both getters and setters):

8.3. Comments
User comments can be added between blocks, and miniBloq will also add the text as a commented line in the geneated code. Also, miniBloq will do this in real time!
The comments block is the following (you can find it in the Actions picker):

9. Supported hardware
9.1. Directly working hardware
miniBloq is an environment that can work with different boards and hardware. Here you will find a list with the boards that can be selected by name in miniBloq's official distribution (we call them "directly working hardware"):

Arduino™ Uno
Arduino™ Duemilanove Mega328 (tested with a clon)
Arduino™ Duemilanove Mega168
Arduino™ Mega 2560
Arduino™ Mega 1280 (tested with a clon)
DuinoBot.Kids.v1.x
DuinoBot.v1.x
DuinoBot.v1.x.HID
Seeeduino v2.2 Mega328
Seeeduino Mega 1280
Maple Rev 5 (preliminary)
Maple Rev 3 (preliminary)
ATTiny25/45/85 (preliminary, with AVR-Doper programmer or with ArduinoISP)

9.2. Indirectly working hardware
There are boards that, although not listed on miniBloq's GUI, may work selecting another compatible board from the list. Some of them will be mentioned here, with the board that must be selected between [brackets]:

Arduino™ Mega ADK   [Arduino™ Mega 2560] (not tested / no USB Host support)
Arduino™ Diecimila   [Arduino™ Duemilanove Mega168] (not tested)
Arduino™ Nano Mega328   [Arduino™ Duemilanove Mega328] (tested with a clon)
Arduino™ Nano Mega168   [Arduino™ Duemilanove Mega168] (not tested)

If you know of any other board that is already working with miniBloq, please contact us (with a comment here, or a @mention in Twitter. Thanks!).

9.3. Future supported hardware
More hardware will be added to the list of supported boards. We are working to have a future miniBloq version which will enable advanced users to add more hardware by themselves.


10. Shortcuts, mouse wheel and the like
10.1. Component Editor shortcuts
The idea is to provide full keyboard navigation in the future. By now, these are the implemented shortcuts:
  • Alt + Delete: Deletes the selected block.
  • Alt + Arrow keys: Moves the current block.
  • Alt + Home: Goes to the first block in the same line.
  • Alt + End: Goes to the last block in the same line.
  • Ctrl + Home: Goes to the first block.
  • Ctrl + End: Goes to the last block.
  • Ctrl + Arrow keys: Scroll.
  • Ctrl + Alt + Home: No matter where you scrolled the program, this restores it to home position.
  • Ctrl + "+" / Ctrl+"-": Zoom in / Zoom out.
  • Ctrl + 0: Restores zoom to 100% (just like some web browsers).

10.2. Shortcuts for menus
The shortcuts for miniBloq's menus will be the same, regardless of the selected user interface language (some programs change their shorcuts if the user selects Spanish, English, Italian, etc., but that's not the idea with miniBloq). Here are the current shortcuts for menus:
  • Alt + F: Unfolds the File menu.
  • Alt + E: Unfolds the Edit menu.
  • Alt + C: Unfolds the Component menu.
  • Alt + V: Unfolds the View menu.

  • Ctrl + O: File->Open.
  • Ctrl + S: File->Save.
  • Alt + F4: File->Exit.

  • Ctrl + X: Edit->Cut.
  • Ctrl + V: Edit->Paste.
  • Alt + Del: Edit->Delete.

  • Ctrl + U: Component->Run.
  • Ctrl + R: Component->Build.
  • Alt + D: Component->Open folder.

  • Ctrl + H: View->Help and Resource Center.
  • Alt + Q: View->Quick toolbar.
  • Alt + G: View->Generated code.
  • Alt + H: View->Hardware.
  • Alt + P: View->Properties.
  • Alt + M: View->Messages.
  • Alt + T: View->Terminal.

10.3. Mouse and mouse wheel
If you have a mouse with mouse wheel, this are the possible usages in the Component Editor:
  • Mouse wheel only: Vertical Scroll.
  • Mouse wheel + Shift: Horizontal Scroll.
  • Mouse wheel + Ctrl: Zoom in / Zoom out

And these are the actions associated with mouse buttons in the Component Editor:
  • Left click over a block: Selects it as the current block.
  • Right click over a block: Displays the context menu.
  • By pressing the middle button (or the wheel in most modern mouses) over the Component Editor's background, you can drag the complete set of blocks in your program.

Other GUI elements also have actions associated with the mouse wheel and with mouse clicks. The following applies to the Code Viewer (or "Generated code window"), the Terminal and the Messages window:
  • Mouse wheel only: Vertical Scroll.
  • Mouse wheel + Ctrl: Zoom in / Zoom out
  • Right click over the background or over selected text: Displays the context menu (NOTE: This context menu does not support internationalization by now, so you will always see it in English, no matter which language is selected in miniBloq'a GUI).

11. Development tools
miniBloq is being developed with open source development tools and libraries, ranging from the compiler up to the image edition software. To learn more about the tools used to develop miniBloq, please visit the Development page.


12. History
miniBloq descends from Minibloques, a program developed by Julián da Silva Gillig from 1995 to 1997, and published that year. It was free but not open source, and was used in primary and secondary schools in Argentina, with a parallel port robotics interface (called "i-723") manufactured by Simple Informática (a company which does not exists anymore). Minibloques runs under Windows 3.1, Windows 95 and Windows 98.  Here is a screenshoot:


Minibloques was also deployed from 1997 with Tencki kits (in a version called "TenckiBloques"). Those products were also oriented to teach robotics and technology to kids. Later, between the years 2005 and 2007, another company, called XiOR, worked on a derived graphical programming environment for their educational robotics brand Multiplo, which is now developed and manufactured by RobotGroup. In later 2007 Julián started the XDF, a bigger project to develop a robotic's software framework (XiOR was making bigger robots too, like the Sphinx). And miniBloq was one of it's components. The XDF received funding from FONSOFT (an agency belonging to the Argentine Government, dedicated to fund software projects). But miniBloq grew as a project by itself. It was supported by RobotGroup, and lately was funded on a Kickstarter's campaign in 2011:



miniBloq is also one of the environments deployed with Multiplo kits, also funded in a successful Kickstarter campaign in 2012:

13. License
miniBloq is distributed under the RobotGroup-Multiplo Pacifist License (RMPL), either version 1.0 of the licence, or (at your option) any later version. The license can also be downloaded in Spanish (in this link).


14. Links
14.1. Forums (English)
14.2. Forums (Español)
14.3. Robotics and physical computing hardware
14.4. Related projects
Subscribe to: Posts (Atom)