[GitHub]

Extension List

List: click here [Update at any time, search keyword ext in the user library to view the full list]

----------

1-Introduction

MindPlus-User Library Extension-Document for Developers

Mind+ is a Scratch 3.0-based programming software that supports various open-source hardware such as Arduino, micro: bit, mPython-esp32 and all kinds of controller boards. You can build a program by dragging and snapping coding blocks, or using advanced programming language like python, c, c++. It can help you to easily experience the joy of creation!

Note: although adding a user library is not too hard, it is still recommended for users with a certain code experience to operate. If you want to add a new module but know nothing about coding, please give feedback to our official team.

Please update your Mind+ software to V1.6.2 RC2.0 and above before adding a user library.

----------

2-User Library File Structure

└─newExtensions                    // Project name 
    │  config.json                 // The configuration file of this user library 
    │  LICENSE.TXT                 // License description
    │  README.md                   // Document description
    │
    └─arduinoC                     // Arduino mode user library root directory
        │  main.ts                 // Graphical block description file
        │
        ├─libraries                // Arduino library file, list all .c, .h, or .cpp files that need to be referenced by this extension library 
        │  └─oled12864
        │          oled12864.cpp
        │          oled12864.h
        │          qrcode.c
        │          qrcode.h
        │
        ├─_images                  // Image files
        │      featured.png        // Display images for MindPlus extension library 
        │      icon.svg            // Icon file for MindPlus graphical block
        │
        ├─_locales                 // Translation file, support for multiple languages
        │      zh-cn.json
        │      en.json
        │
        └─_menus                   // Drop-down menu parameter, can be set independently for each board 
                leonardo.json
                uno.json
                nano.json
                mega2560.json
                microbit.json
                mpython.json

扩展库文件架构图

----------

3-File Description

3.1-config.json Configuration File

{
    "name": {
        "zh-cn": "OLED-12864显示屏(测试)",
        "en": "OLED-12864 screen(Test)"
    },
    "description": {
        "zh-cn": "小体积显示屏,可用于智能穿戴设备的显示器",
        "en": "I2C OLED-2864 Display Module"
    },
    "author": "DFRobot",
    "email": "MindPlus@dfrobot.com",
    "license": "MIT",
    "isBoard": false,
    "id": "oled12864",
    "platform": ["win", "mac", "web"],
    "asset": {
        "arduinoC": {
            "dir": "arduinoC/",
            "version": "0.0.1",
            "board": ["microbit", "esp32"],
            "main": "main.ts",
            "files": ["note":" this field has been auto-generated, no need to fill in "
                "_locales/zh-cn.json",
                "_images/icon.svg",
                "libraries/oled12864/oled12864.cpp",
                "libraries/oled12864/oled12864.h",
                "libraries/oled12864/qrcode.c",
                "libraries/oled12864/qrcode.h"
            ]
        }
    }
}

Detailed description:

  • name: name. The title name of the module displayed in extension library.
  • description: description. The description of the module displayed in extension library.
  • author: author. Please use English letters.
  • email: email. When the version update needs to modify the user library or there is feedback from users, the developer will be notified by email. (Pre-reserved function)
  • license: license type.
  • isBoard: main-controller. Whether the current extension is the main-controller (pre-reserved function, false).
  • id: used to distinguish the module. Different modules of the same author need to set different ids. It is recommended to use English and number symbols for naming.
  • platform: supported platform. There are 3 options:“win" for windows desktop version of mind+, "mac" for Mac desktop version and "web" for webpage version. (Mind+ Web version only supports for Windows currently.)
  • asset: mode configuration. Only support for the Arduino C mode in Offline mode.
  • dir: specify the mode path. The / cannot be missed. For example, "dir": "arduinoC/". It is not recommended to modify. Version: version information. It includes three numbers that are generally assigned in creasing order and correspond the new developments in the software (reserved function for version control).
  • board: specify the supported main-boards, the related field is shown below. Before adding the corresponding supported main-controller, make sure the test is passed.
  • main:the file name of block description file. It should be a ts-suffix file with user-defined name at the corresponding path, such as, main.ts.
  • files: the path of necessary file is included for loading. Note: This field is deleted from 1.6.2RC2.0, and related files are automatically added when compiling and exporting the library.

Main-controller List

Main-controller Type Name
UNO Main-controller board arduino
Nano Main-controller board arduinonano
Leonardo Main-controller board leonardo
Micro:Bit Main-controller board microbit
mpython Main-controller board esp32
Mega2560 Main-controller board mega2560
Vortex Kit vortex
Romeo Kit romeo
UNOR3 Kit arduinounor3
Max:Bot Kit maxbot
Maqueen Kit maqueen
Max Kit max

----------

3.2-main.ts Description File Overview

enum xxxx {
   //% Define pin description content, menu item that needs to be translated should be defined in the menu file
   //% Define pin generated code
 }


//% color="#xxxx"   Define the appearance of the entire extended block by the description content behind //%
namespace xxxx {  

    //% block="xxx [xxx]" blockType="xxx" The description content of the appearance definition for the first block  
    //% block Other description content 
    export function xxxx(parameter: any, block: any) {  //Definition of generated code for a single block, describe the code location and content by function 
        //Description of the generated code location and content 
    }

    //% block="xxx [xxx]" blockType="xxx" Description content of the appearance definition for the second block 
    //% block other description content  
    export function xxxx(parameter: any, block: any) {
       //The location and content of generated code
    }

    //% block="xxx [xxx]" blockType="xxx"  Description content of the appearance definition for the n block 
    //% block other description content 
    export function xxxx(parameter: any, block: any) {
       //The location and content of generated code
    }

}

For example:

The codes in main.ts are shown below:

//% block="when press [BUTTON]" blockType="hat"
//% BUTTON.shadow="dropdown" BUTTON.options="BTN" BUTTON.defl="BTN.A"
export function myBlock(parameter: any, block: any) {
    let button = parameter.BUTTON.code;
    Generator.addInclude('Mylibraray', '#include <Mylibraray.h>');
    Generator.addObject(`libraray`, `MY_Libraray`, `libraray;`);
    Generator.addEvent("functionName", "String", "functionName", "String message, int8_t error", true);
    Generator.addSetup("libraray.begin", `libraray.begin(${button});`);
    Generator.addSetup(`libraray.callback`, `libraray.callback(functionName);`);
    Generator.addCode('libraray.start();')
}

Effect:

  • The generated block:
  • The generated code:
/*!
 * MindPlus
 * microbit
 *
 */
#include <Mylibraray.h>

// Function declaration
String functionName(String message, int8_t error);
// Create an object
MY_Libraray libraray;


// Main program starts
void setup() {
    libraray.begin(A);
    libraray.callback(functionName);
    libraray.start();
}
void loop() {

}

// Callback function
String functionName(String message, int8_t error) {

}

3.2.1-Define Block Appearance

General Rules for Description

The description commands must be put behind the descriptor //%.

Command Definition Acting Position Selectable Parameter
color Set color namespace and block 24-bit true color
iconWidth The width of icon namespace Default to 40
iconHeight The height of iocn namespace Default to 40
board Specify the main-controller or kit supported by the current block. Separate the multiple boards by commas block arduino、leonardo、microbit、esp32、arduinonano、mega2560、vortex、romeo、 arduinounor3、maxbot、maqueen、max
block Block description block User defined, such as xxx[A]xxx
blockType Block type block hat: hat-shaped, command: Square reporter: circle Boolean: diamond
shadow The type of input box Input box string: text dropdown: with drop-down menu dropdownRound: with drop-down menu and allowing other block to be dragged into it. boolean: Boolean range: range number: number
defl Set default value Input box User-Defined
Params.min Set minimum value Input box of range type User-Defined
Params.max Set maximum value Input box of range type User-Defined
options Specify the content of drop-down menu Input box of menu type User-Defined

###Description Content Limitation

In the block description, some parameter descriptions are obligatory. Refer to the list below:

● Obligatory
⭕ Optional
\ Not necessary

Parameter Field namespace Block definition string : input box number : input box input : box with range boolean : input box dropdown : menu dropdownRound : menu
color \ \ \ \ \ \ \
iconWidth \ \ \ \ \ \ \
iconHeight \ \ \ \ \ \ \
block \ \ \ \ \ \ \
blockType \ \ \ \ \ \ \
shadow \ \
defl \ \
params.min \ \ \ \ \ \ \
params.max \ \ \ \ \ \ \
options \ \ \ \ \ \
block \ \ \ \ \ \ \

namespace

The descriptor in front of namespace can specify the color and icon information of the entire user library. The whole block definition should be included in the curly braces of namespace.

//% color="#AA278D" iconWidth=50 iconHeight=40
namespace module {
    ...
}

Create a TypeScript namespace with all the graphical blocks written in it. We can set the overall color and icon size of the blocks. The block style setting should be included in the descriptor //%. All style settings are not necessary. If these parameters are not set, the system will display the default style. The content contained in //% can be written on one or more lines.

  • Color: set block color, and RGB 24bit true color
  • iconWidth: set the width of icon.
  • iconHeight: set the height of the icon. Icon should be in svg format, and images need to be placed in images file folder root directory.

blockType : Block Appearance

Set the overall appearance of the block by blockType keyword.

//% block="set the line width to [WIDTH] pixels" blockType="command"
export function setBrightness(parameter: any, block: any) {
    ...
}

Define a square graphical block. The content contained in //% can be written on one or more lines.

block外观 blockType值 外观
hat hat
command square
reporter circle
boolean diamond

shadow - Input Box

  • The input box is defined by shadow keyword, and they have 7 kinds: string, dropdown, dropdownRound, Boolean, range, number.
  • The following code will display all types in one block.
  • Defl keyword specifies the default display parameter.
  • Options keyword specifies the dropdown menu option. Define an enum in the ts file. If you need to distinguish main-boards, place the pin definition in _menus folder root directory.
  • Specify the params.min and params.max in the input box of range type.
//% //% block="test for all types of input box:text:[SS] number [SN]  boolean:[SB] range [SR] dropdown:[SD] dropdownRound:[SDR] "  blockType="command"
//% SS.shadow="string"   SS.defl="mind+"
//% SN.shadow="number"   SN.defl="123"
//% SB.shadow="boolean"  
//% SR.shadow="range"   SR.params.min=0    SR.params.max=10    SR.defl=5
//% SD.shadow="dropdown"   SD.options="BTN"     SD.defl="BTN.B"
//% SDR.shadow="dropdownRound"   SDR.options="LINE"     SDR.defl="LINE.1"

export function myBlock(parameter: any, block: any) {

}


3.2.2-Generator - Code Definition

Generator is a tool used to provide the generated code. It is built in the mindplus interpreter to call and control the specification of the generated code.

Generator.addInclude(id, code, cover)

Add include in global zone.

  • id: identifier
  • code: code
  • cover: whether to override the code with same id, default to False. This parameter can realize the linkage between multiple blocks. For example, if the serial port is not initialized, the block will generate code with 9600 band rate by default. When it used the initialization with band rate 115200, the block will generate code with 115200 band rate accordingly.

For example:

  • main.ts:Generator.addInclude("Mylibraray", "Mylibraray.h", True);
  • arduino.ino:#include <Mylibraray.h>"

Generator.addObject(id, type, code, cover)

Add include in global zone.

  • id: identifier
  • type: class name
  • code: object name
  • cover: whether to override the code with same id, default to false.

For example:

  • main.ts:Generator.addObject(`libraray`, `MY_Libraray`, `libraray;`);
  • arduino.ino:MY_Libraray ibraray;

Generator.addSetup(id, code, cover)

Add code in setup.

  • id: identifier
  • code: code
  • cover: whether to override the code with same id, default to false.

Generator.addCode(code)

Add code without return in setup or loop. (Hat, square block)

  • code: code。

Generator.addCode([code, level])

Add code with return in setup or loop. (circle, diamond).

  • code:code that needs to be registered.
  • level:[Operator precedence](#Operator precedence)dd parentheses for codes. It is recommended to set as:Generator.ORDER_UNARY_POSTFIX。 For example::Generator.addCode([libraray.read()", Generator.ORDER_UNARY_POSTFIX]);

Generator.addEvent(id, type, nam, args, cover)

Define a callback function in global zone.

  • id: identifier
  • type: the type of return value, compliant with C++ rules.
  • name: function name, compliant with c++ rules.
  • args: function arguments, compliant with c++ rules.
  • cover: whether to override the code with same id, default to false.
    For example:Generator.addEvent("addEvent", "void", "function", "int x,int y");

Operator precedence

Command Level Suitable Range
Generator.ORDER_UNARY_POSTFIX 1 expr++ expr-- () [] .
Generator.ORDER_UNARY_PREFIX 2 -expr !expr ~expr ++expr --expr
Generator.ORDER_MULTIPLICATIVE 3 * / % ~/
Generator.ORDER_ADDITIVE 4 + -
Generator.ORDER_SHIFT 5 << >>
Generator.ORDER_RELATIONAL 6 >= > <= <
Generator.ORDER_EQUALITY 7 == != === !==
Generator.ORDER_BITWISE_AND 8 &
Generator.ORDER_BITWISE_XOR 9 ^
Generator.ORDER_BITWISE_OR 10 |
Generator.ORDER_LOGICAL_AND 11 &&
Generator.ORDER_LOGICAL_OR 12 ||
Generator.ORDER_CONDITIONAL 13 expr ? expr : expr
Generator.ORDER_ASSIGNMENT 14 = *= /= ~/= %= += -= <<= >>= &= ^=
* The smaller the number, the higher the level

Generator.board

The code returns the type of the main-board selected currently, by which to generate different codes in various main-board with one block.

For example:

if(Generator.board === 'arduino'){// if it is arduinouno, generate code as below:
     Generator.addSetup("GTSerialSetup",`${ser}.begin(9600);`);
}else if(Generator.board === 'esp32'){//if it is mPython, generate code as below.
    Generator.addSetup("GTSerialSetup",`${ser}.begin(9600,${rx}, ${tx});`);
}

Main-controller List

Main-controller Type Name
UNO Main-controller board arduino
Nano Main-controller board arduinonano
Leonardo Main-controller board leonardo
Micro:Bit Main-controller board microbit
mpython Main-controller board esp32
Mega2560 Main-controller board mega2560
Vortex Kit vortex
Romeo Kit romeo
UNOR3 Kit arduinounor3
Max:Bot Kit maxbot
Maqueen Kit maqueen
Max Kit max

----------

3.3-Resource Folder

3.3.1-_images

This file can be used to store the resource files of images.

  • featured.png featured.png represents the images in extension interface, and the name should not be modified. These images are in .png format with 600*374 pixel.
  • icon.svg The icon file starts with icon.svg block, and holds vetorgram (svg). The name should not be modified. You need to add the file path in config.json.

3.3.1-_locales

  • The language is displayed according to the file name. If there is no such file, it will directly display the language defined by block in main.ts.
  • Language List:
Language File Name Language
zh-cn.json Chinese (Simplified)
es-419.json Spanish(South America)
fr.json French
ko.json Korean
th.json Thai
tr.json Turkish
mn.json Mongolian
zh-tw.json Chinese (Traditional)

3.3.1-_menus

  • This folder holds the contents of the drop-down menu for different boards.

3.3.1-libraries

  • This file holds the Arduino library files that will be called when generating code.

----------

4-An Example on User Library

Aim

Complete an OLED display library and achieve some advanced functions.

Preparation

Text Editor: VS code (recommended) *library: as per your needs. *Block design: predict how the block should be displayed according to its functions. *Image design: prepare a png image of 600372 pixel. *Icon design: find free icon on the internet or use software like inkscape to design one.

扩展库文件架构图

Step

(For detailed information, refer to the example library: https://github.com/dfrobot/ext-oled12864.git)

  1. Edit the config.json configuration file to configure the extension library information. Refer to “3.1-config.json Configuration File”.
  2. Edit the main.ts description file to configure the appearance of block. Refer to “3.2.1- Block Appearance Definition”.
  3. Edit the main.ts description file to configure the generated code of the block. Refer to “3.2.2-Generator Code Definition”.
  4. Edit _menus, _locales menu file according to the needs of main.ts. Refer to “3.2.1-Define Block Appearance”.
  5. Put the corresponding files into _images, libraries files. Refer to “3.2.1-Define Block Appearance”.

Test

1.Function test (update the library by loading the config.json locally), check if the generated block and code are as expected and whether the compilation is successful. 2.Adjust the type of the mainboard config.json supports and test the adaptability of different main boards. (Note: the compilation must be successful.)

Export and Share

  1. After you debugged the program, write the README.md file (In Markdown format).
  2. Right-click extension library to export the user library as .mpext file.
  3. Share your work with others on our Mind+ community:
    • Load locally: directly share with other users by loading .mpext (Please note that do not decompress and upload from local, otherwise it will be in debug mode. You need to directly select .mpext to load and open).
    • Network loading: put the .mpext file in the same directory as config.json, upload the entire folder to github or gitee (code cloud) through git, and share the git link to other users for loading.

Note: 1.6.2RC2.0 needs to put the config.json and libraries.zip in the exported .mpext file (can be unzipped and extracted) to the corresponding location of the development folder, and then upload git, otherwise it will cause loading errors. (The future version will directly load from git via mpext file, so this operation can be ignored.)

5-Excellent User Libraries

Search keyword to load excellent user library.

6-FAQ

FAQ
Question I need to control a function code to begenerated in setup, the parameter could be various according to the drop-down item I selected, but the same id in setup can only generate one code. Is there a way to deal withthis problem?
Solution The input item of the drop-down menucan be used as id. In this way, the different drop-downs you selected will be different ids, by which it will generate multiple codes.

FAQ
Question When the drop-down menu switched, why the generated code cannot be changed?
Solution Use string concatenation operator and ${} to switch the generated code of drop-down menu.

FAQ
Question There is no error in the block of main.ts, but the input box cannot be used after importing.
Solution chack namespace or Delete the user library and import it again .

FAQ
Question How to distinguish the generated codes of different boards (microbit, mPython-esp32, arduino, etc.) in the Cpp library of Arduino?
Solution Define macro to distinguish, for example:
#if   defined(NRF5)
//Code compiled by the compiler when selecting microbit as main-board
#elif defined (ESP_PLATFORM)
//Code compiled by the compiler when selecting mPython as main-board
#else
//Code compiled by the compiler when selecting others as main-board
#endif

If you have any questions, you can join to communicate with us through forums and emails.