I've been communicating with Julian since I joined the v0.8 alpha testing and I now have a fair idea of his roadmap for Minibloq. The Minibloq UI is stable and usable but the structure of the Components\Minibloq\Lib\Cpp\* sub-folders is only a first shot to get Minibloq released.
I've guessed enough as to how the blocks and associated source code hang together for v0.8 but expect much to change with each new release (eg the naming conventions of the matrix files changed between v0.8 alpha and v0.8 beta). We'll have a much better idea when Julian has had time to revisit the block xml. Once he's happy with his xml dialect that's when he'll probably document it but that might be in a few releases time.
The changes.rar file I uploaded to the Blocks forum reflects what I did to get the custom blocks I needed to work for the project at school. I haven't made any attempt to make the source code cross-platform (the school only has Arduino Unos) and I could probably have merged all the Moving Average stuff under a single block folder. But what I've done works!
A full tutorial will only be possible once Julian has refactored his code structure but for the time being here's what I did ...
1. Source code files
Julian has some of his source code in a "Sources" sub-folder of the block itself (eg Components\Minibloq\Lib\CPP\Blocks\action.020.0060.Motor.Arduino.v1.0\Sources) but I couldn't work out how to get it to compile with the source there so I put my source under the Target folder (eg Components\Minibloq\Lib\CPP\Targets\ArduinoUNO_Arduino.v1.0\Core\ArduinoUNO_0022\SeeedStudio_ElectronicBrick_RealTimeClock). I created a sub-folder to support each class I added. Rather than re-create a core.a file whenever I changed my source I simply modified the Components\Minibloq\Lib\CPP\Targets\ArduinoUNO_Arduino.v1.0\Core\Minibloq.h file and added the following ...
- Code: Select all
// ML Begin
// include the source files instead of the header files ... this inserts the code into the link stream and saves having to create a core.a file
#include "ManyLeaves_MovingAverage/ManyLeaves_MovingAverage.cpp"
#include "ManyLeaves_SchoolToiletBlock/ManyLeaves_SchoolToiletBlock.cpp"
#include "SeeedStudio_WaterFlowSensor/SeeedStudio_WaterFlowSensor.cpp"
#include "SeeedStudio_ElectronicBrick_RealTimeClock/SeeedStudio_ElectronicBrick_RealTimeClock.cpp"
// Wire needed for SeeedStudio_ElectronicBrick_RealTimeClock
#include "Wire/utility/twi.c"
#include "Wire/Wire.cpp"
// ML End
... you'll notice that it includes the cpp files not the h files ... not ideal but it works!
2. Block files
I added the following sub-folders to the Components\Minibloq\Lib\CPP\Blocks folder.
- action.200.0110.ManyLeaves_MovingAverage_AddValue.v1.0
action.200.0100.ManyLeaves_MovingAverage_SetLength.v1.0
number.200.0100.SeeedStudio_WaterFlowSensor.v1.0
number.200.0110.SeeedStudio_ElectronicBrick_RealTimeClock_GetTime.v1.0
number.200.0120.ManyLeaves_SchoolToiletBlock_GetMinutes.v1.0
number.200.0130.ManyLeaves_MovingAverage_GetValue.v1.0
"action" indicates that the block should appear in the action palette (ie the block is a "setter"). "number" indicates that the block returns a number and should appear in the number palette (ie the block is a "getter"). The next two numbers seem to be the row and column to use within the palette (ie allows some ability to sort)
Each block folder contains at least three entries: a Doc sub-folder (tooltip text), an Images sub-folder (onscreen images) and a main.block file.
If your block is called main.block, Minibloq looks for a corresponding main.english or main.spanish file in the Doc sub-folder to show as the tooltip. If your block is called fred.block, Minibloq would look for fred.english or fred.spanish file as appropriate.
The image files in the Images sub-folder are directly referenced within the block file xml (eg main.block).
The xml content of main.block is where it all gets a bit mysterious. Without any documentation I just looked at a few of Julian's own blocks and guessed what might work:
a. function element within properties element: Setter for an action and Sensor or Getter for a number.
b. code element: I just hacked around here without any real idea what I was doing however the elements starting with param do seem to respect the elements within the params element at the bottom of the block file
c. interface element: all I did was change the values linking to the image files. I'm no graphic artist so all links are to a single png file. Within the interface elements of some of Julian's blocks there are also hasInstanceNameField, instanceNameFieldSorted and instanceType elements. I guess they are to do with related sub-blocks but I couldn't work it out. That's why all my Moving Average blocks are in separate folders.
3. Matrix files
The matrix files (all of which are empty - only the names are important) are an early attempt at a relational-style filter for the blocks on screen. In v0.8 it provides a list of all the valid blocks for the chosen Target. In future releases, Julian plans to provide the ability to filter on additional criteria.
I added the following matrix file entries to the Components\Minibloq\Lib\CPP\Targets\ArduinoUNO_Arduino.v1.0\Matrix folder.
- action.200.0110.ManyLeaves_MovingAverage_AddValue.v1.0.rel
action.200.0100.ManyLeaves_MovingAverage_SetLength.v1.0.rel
number.200.0100.SeeedStudio_WaterFlowSensor.v1.0.rel
number.200.0110.SeeedStudio_ElectronicBrick_RealTimeClock_GetTime.v1.0.rel
number.200.0120.ManyLeaves_SchoolToiletBlock_GetMinutes.v1.0.rel
number.200.0130.ManyLeaves_MovingAverage_GetValue.v1.0.rel
You'll notice the name of the matrix file is the same as the corresponding block sub-folder with a ".rel" extension.
4. Changes.rar
I downloaded "eXpress TimeStamp Toucher" off the internet (there are many similar products out there) so I could change the time stamp on all of Julian's files to a set date/time. I then changed the date/time on all my changes to a leter date/time (which is what occurs naturally if you develop after an install). This enables me to run the following Windows cmd script to automatically create a rar file of all my changes.
- Code: Select all
setlocal
rem we want the changes since /D:
set recent=/Y /I /D:10-24-2011
rem xcopy the changes to temporary folder %changes%
set changes=".\changes"
md %changes%
xcopy /S %recent% ".\Components" %changes%
rem use winrar command-line tool to archive
set rarexe="C:\Program Files\WinRAR\rar.exe"
set rarout=changes.rar
erase %rarout%
%rarexe% a %rarout% %changes%
rem %rarexe% a %rarout% changes.cmd
rem remove temporary folder %changes%
rd /S /Q %changes%
endlocal
I plan to update all my changes to "best practice" after each new release from Julian and upload the changes.rar file to this forum.
This isn't much of a tutorial but it might help a few of you get started
Andrew