API List
app.getVersion
Function: Obtains the version of the current API
Available versions: V1.0.0 or later
Parameter: None
Return: string
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
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
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
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
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
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
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
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
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
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
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
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);
// ......
}