API List

app.getVersion

Function: Obtains the version of the current API
Available versions: V1.0.0 or later
Parameter: None
Return: string

:::info Note: This is an asynchronous function that requires the await keyword when being called. :::

Example:

// (onRun)
async (args, app, device, block) => {
    return await app.getVersion();
}

app.log

Function: Prints Information to the Web debug window, same function as console. Log
Available versions: V1.0.0 or later
Parameter:
…msgs[], multiple output strings
Return: None

Example:

app.log("blah-blah","no one", "nothing", 1, true);

app.warn

Function: Prints warning information to the Web debug window, same function as console. warn
Available versions: V1.0.0 or later
Parameter:
…msgs[], multiple output strings
Return: None

Example:

app.warn("something dangerous");

app.error

Function: Prints error information to the Web debug window, same function as with console. error
Available versions: V1.0.0 or later
Parameter:
…msgs[], multiple output strings
Return: None

Example:

app.error("fatal!");

app.workspace.broadcast

Function: Initiates an mBlock broadcast
Available versions: V1.0.0 or later
Parameter: message:string, message name
Return: None

Example:

// The following simulates the block: broadcast (message)
(args, app, device, block) => {
    app.workspace.broadcast(args.MSG);
}

app .workspace .onBroadcast

Function: Executes the subsequent statements when receiving the broadcast of mBlock
Available versions: V1.0.0 or later
Parameter: message:string, message name
Return: None

Example:

const _cancel = app.workspace.onBroadcast(msg => {
    app.log('got a message from mblock:', msg);
});
// ...
// to cancel this event handler
// _cancel()
// The following simulates the block: when I receive (message)
// onRun
(args, app, device, block) => {
    if (self._ON_BROADCAST_MSG == args.MSG) {
        self._ON_BROADCAST_MSG = null;
        return true; // true indicates that the hat block is triggered
    } else {
        return false; // false indicates that the hat block is not triggered
    }
}
// onAdd
(app, device, block) => {
    // Registration message event, the global variable  self.__ON_BROADCAST_CANCELLER stores "deregistration"
    self.__ON_BROADCAST_CANCELLER = app.workspace.onBroadcast(msg => {
        self._ON_BROADCAST_MSG = msg; // Global variable self.__ON_BROADCAST_MSG stores the received broadcast variable
        app.workspace.runBlocks(block.opcode);
    });
}
// onRemove
(app, device, block) => {
    if (self.__ON_BROCAST_CANCELLER) self.__ON_BROCAST_CANCELLER();
}

app.workspace.getVariable

Function: Obtains a variable of mBlock. Note that this API is available only for global variable names.
Available versions: V1.0.0 or later
Parameter: varName:string, variable name
Return: value: string | number, variable value

:::info Note: This is an asynchronous function that requires the await keyword when being called. :::

Example:

// The following simulates the block: variable
async (args, app, device, block) => {
    return await app.workspace.getVariable(args.VAR);
}

app.workspace.setVariable

Function: Sets a variable name and value of mBlock. Note that this API is available only for global variable names.
Available versions: V1.0.0 or later
Parameter:
varName:string, variable name
value: string | number, variable value
Return: void

Example:

// The following simulates the block: set <variable> to <numeric value>
// onRun
async (args, app, device, block) => {
    await app.workspace.setVariable(args.VAR, args.VAL);
}

app.workspace.runBlocks

Function: Executes a hat block. Note that it does not necessarily trigger the hat block. After .onRun is executed, whether the hat block is triggered depends on the result returned.
Available versions: V1.0.0 or later
Parameter:
opcode: string, block opcode
coldDown?: number, colddonw time (ms) (optional, applied to throttle in scenarios where triggering is frequently performed. The default value is 50 ms.
Return: void

:::info Note: This is an asynchronous function that requires the await keyword when being called. :::

Example:

await app.workspace.runBlocks('your_extension_id.block_id');

app.workspace.disableBlocks

Function: Disables a block.
Available versions: V1.0.0 or later
Parameter:
…opcodes: string[], block ID
Return: None

Example:

app.workspace.disableBlocks('your_extension_id.block_1', 'your_extension_id.block_2', 'your_extension_id.block_3')
// you cannot use these blocks from now
// The following block function disables the block itself.
(args, app, device, block) => {
    app.workspace.disableBlocks(block.opcode);
}

app.workspace.enableBlocks

Function: Enables a block.
Available versions: V1.0.0 or later
Parameter:
…opcodes: string[], block ID
Return: None

Example:

app.workspace.enableBlocks('your_extension_id.block_1', 'your_extension_id.block_2', 'your_extension_id.block_3')
// you can use these blocks again

app.workspace.resetEvents

Function: Resets block events, usually used when a device is programmed in the live mode
Available versions: V1.0.0 or later
Parameter: None
Return: None

Example:

function onConnect(app, device) {
  // sometimes device may disconnect by accident, then the state of mblock communicate to device is messed up, you need to reset it.
  app.workspace.resetEvents();
}

app.sendMessage

Function: Transmits events across different extensions. Different from app.workspace.broadcast, this API does not interact with mBlock.
Available versions: V1.0.0 or later
Parameter:
msgName: string, message name
…datas: any[], message data
Return: None

Example:

// in one extension/file ......
app.sendMessage("echo", 1234)；
// in other extension/file ......
app.subscribeMessage ("echo", datas=>{ 
    app.sendMessage("echo back", datas);
} )

app.subscribeMessage

Function: Receives events across different extensions. The events are not accumulated. The current registration cancels the last registration.
Available versions: V1.0.0 or later
Parameter:
msgName: string, message name
handle: function, event response function
Return: None

Example:

// in one file ......
app.sendMessage("echo", 1234)；
// in other files ......
app.subscribeMessage ("echo", (datas)=>{ 
    app.sendMessage("echo back", datas);
} )

app.receiveMessage

Function: Receives events across different extensions, waiting return asynchronously (async/await)
Available versions: V1.0.0 or later
Parameter:
msgName: string, message name
Return: Data returned asynchronously by promise

Example:

// in one file ......
app.sendMessage("echo", ["balabala", 1234])；
// in other files ......
let datas = await app.receiveMessage("echo");
app.log('received datas of ${datas}');

target.id / device.id

Function: Obtains a device ID.
Available versions: V1.0.0 or later
Parameter: None
Return: string, name

Example:

// The following block function returns the ID of the current device:
(args, app, device, block) => {
    return device.id;
}

device.isSelected

Function: Determines whether a device is currently selected/edited
Available versions: V1.0.0 or later
Parameter: None
Return: string, name

:::info Note: This is an asynchronous function that requires the await keyword when being called. :::

Example:
The following block function returns whether the current block is selected.

async (args, app, device, block) => {
    return await device.isSelected();
}

device.getCode

Function: Obtains the converted code (if code conversion is allowed)
Available versions: V1.0.0 or later
Parameter: None
Return: ICode, containing the type and text fields, as shown in example

:::info Note: This is an asynchronous function that requires the await keyword when being called. :::

Example:

async (args, app, device, block) => {
    let {type, text} = await device.getCode();
    console.log(`code of ${type}: ${text}`);
    return text;
}

device.writeRaw

Function: Writes data in bytes to a device through a serial port or Bluetooth
Available versions: V1.0.0 or later
Parameter:
data: number[]
channel?: string, channel name, optional. The default value is “”.
Return: None

Example:

device.writeRaw([0xff, 0xff]);

device.setTextDecder

Function: Sets the text decoding type
Available versions: V1.0.0 or later
Parameter: decoderType : ‘utf8’ | ‘ascii’, decoding type
Return: None

Example:

device.setTextDecoder('utf8');

device.writeText

Function: Writes data in texts to a device
Available versions: V1.0.0 or later
Parameter:
text: string, text
channel?: string, channel name, optional. The default value is “”.
Return: Uint8Array

Example:

device.setTextDecoder('utf8');
device.writeText('text');

device.readText

Function: Reads data in texts from the buffer. Note that the data is directly returned from the buffer.
Available versions: V1.0.0 or later
Parameter: consume?: bool, whether to delete data from the buffer after reading it. The default value is true.
Return: string

:::info Note: This is an asynchronous function that requires the await keyword when being called. :::

Example:

device.setTextDecoder('utf8');
let text = await device.readText();
app.log('text received from device', text);

device.writeHex

Function: Writes data in bytes to a serial port, represented in a hexadecimal string
Available versions: V1.0.0 or later
Parameter:
text: string, hexadecimal string
channel?: string, channel name, optional. The default value is “”.
Return: None

Example:

device.writeHex('eeff00');

device.readHex

Function: Reads data in bytes from the buffer, represented in a hexadecimal string
Available versions: V1.0.0 or later
Parameter:
consume?: bool, whether to delete data from the buffer after reading it, optional. The default value is true.
Return: string

:::info Note: This is an asynchronous function that requires the await keyword when being called. :::

Example:

'let hexStr = device.readHex();
app.log('hex received from device', hexStr);

device.asyncReadProtocol

Function: Reads protocol data asynchronously. The protocol data is returned when it meets the protocol format. (For details, see the protocol communication description document.)
Available versions: V1.0.0 or later
Parameter:
protocolName: string, protocol name
pattern: any[], format
timeout? : number, timeout time in ms, optional. The default value is 3,000 ms.
Return: Promise

:::info Note: This is an asynchronous function that requires the await keyword when being called. :::

Example:

let datas = await device.asyncReadProtocol('your_protocol', ["ff55", 'string', 'float']);
if(datas == null) {
    app.log('receive nothing or not a valid protocol');
} else {
    app.log('receive datas, string of ${datas[0]}, float of ${datas[1]}');
}

device.asyncWriteProtocol

Function: Writes data and encapsulates it into a protocol. Note that this is an asynchronous function that requires the await keyword. (For details, see the the protocol communication description document.)
Available versions: V1.0.0 or later
Parameter:
protocolStr: string, protocol name
pattern: any[], format
channel?: string, channel, see device.writeRaw
Return: number[], protocol data

:::info Note: This is an asynchronous function that requires the await keyword when being called. :::

Example:

await device.asyncWriteProtocol('your_protocol', ["ff55", ['string', 'some text'], ['float', 1.1]]);

device.subscribeReadProtocol

Function: Reads protocol data asynchronously. The protocol data triggers the handler when it meets the protocol format. (For details, see the protocol communication description document.)
Available versions: V1.0.0 or later
Parameter:
protocolName: string, protocol name
pattern: any[], format
handler: (datas: any[]) => void, triggering the handler when the protocol data meets the format Return: ()=>void, deregistration

Example:

device.subscribeReadProtocol('your_protocol', ["ff55", 'string', 'float'], (datas)=>{
    app.log('receive datas, string of ${datas[0]}, float of ${datas[1]}');
});

device.isConnected

Function: Determines whether a device is connected
Available versions: V1.0.0 or later
Parameter: None
Return: bool

:::info Note: This is an asynchronous function that requires the await keyword when being called. :::

Example:

onConnect(app, device) {
  if(!(await device.isConnected())){
    app.error('unreachable!');
  }
}

device.isUploadMode

Function: Whether it is in the upload mode or live mode
Available versions: V1.0.0 or later
Parameter: None
Return: bool

:::info Note: This is an asynchronous function that requires the await keyword when being called. :::

Example:

afterChangeUploadMode (app, device) {
  if(!(await device.isUploadMode())){
    app.error('unreachable!');
  }
}

block.opcode

Function: Opcode type of a block
Available versions: V1.0.0 or later
Parameter: None
Return: string

Example:

onRun(args, app, device, block) {
    app.log('start to run block type of ', block.opcode);
    // ......
}

block.id

Function: ID of a block. Blocks of the same opcode types are defined with different IDs.
Available versions: V1.0.0 or later
Parameter: None
Return: string

Example:

onRun(args, app, device, block) {
    app.log('start to run block id of ', block.id);
    // ......
}

block.arguments

Function: Parameter of a block
Available versions: V1.0.0 or later
Parameter: None
Return: any[]

Example:

onRun(args, app, device, block) {
    app.log('start to run block with arg1 of ', block.arguments.ARG1);
    // ......
}