Makeblock mBot Protocol

This document is for developers who want to develop their own apps for Makeblock robots. For beginners, please see “getting started” section in http://learn.makeblock.com/cn

Makeblock mBot Protocol specifies how computer programs or mobile apps talk with Makeblock controller boards (Me Orion, mCore/mBot, MegaPi). Using this protocol, Apps may talk to Makeblock robots through USB cables, Bluetooth, or 2.4G modules (as USB HID device).

Please remember: Makeblock mBot Protocol only works when proper firmware is uploaded to the controller board. The following section describes how to install the firmware.

Installing Firmware

Makeblock mBot Protocol only works with supported firmware. You may install the firmware using mBlock software. The steps are as follows:

  1. Open mBlock software, and connect your controller board to the computer with an USB cable;
  2. From the software menu, select “Connect” Þ “Serial Port” ÞThe specific Serial Port for your USB device (in Windows systems it is usually something like “COM1”; while in Mac it is like “/dev/tty.wchusbserial.” you may need to try multiple times until you find the right port);
  3. From the menu, select “Connect” Þ “Upgrade Firmware”;
  4. Click “Confirm” button in the appeared dialog.

Debugging Makeblock mBot Protocol

mBlock software also provides a way to debug the protocol. Using this tool, you can:

  1. View which actual bytes are sent to the micro-controller by mBlock commands;
  2. Send arbitrary bytes to the micro-controller using HEX format;
  3. View responses from the micro-controller in your computer.

To access the debugging tool, you need:

  1. Open mBlock. Connect your device (mBot, for example) to your computer;
  2. In the menu, select “Connect” Þ “Serial Port” Þthe specific name for your USB device;
  3. In the menu, select “Boards” Þ “mBot” (or the type of your controller board);
  4. In the menu, select “Edit” Þ “Arduino mode”.
  5. Click “char mode” button and change it to “binary mode” (for the convenience to type commands).

The interface looks like this:

orion_debugger_1

For example, if you want move a motor of a mBot, you may type command:

ff 55 06 60 02 0a 09 ff 00

and click the send button, as shown in the following figure:

orion_debugger_2

You may also select “Robots” from the left panel, drag a command to the canvas, and double click it to see the effect and read inputs/outputs with the micro-controller, as shown in the figure below:

debugger-interface

Instruction Formats

Commands sent from the computer to the micro-controller are defined in “frames”. Each frame consists the following parts:

Byte Name Description Type Example
0 Prefix 1 The 2-byte prefix marking the start of the frame MB_MCU_PREFIX_1 0xFF
1 Prefix 2 MB_MCU_PREFIX_2 0x55
2 Length The remaining length of this command Byte (0-255) 0x04
3 Index A custom index specified by the sender. If there is reply, the micro-controller will use the same index provided here to indicate which command it replies Byte (0-255) 0x01
4 Action Read (01) or write (02) MB_MCU_COMMAND_READ

OR

MB_MCU_COMMAND_WRITE

 0x01
5 Device Type of Device (sensors or actuators) Byte (0-255) 0x00
… Payload Remaining data in the frame

 

Response Data Formats

For sensor-reading commands, micro-controller will respond frames in the following formats:

Byte Name Description Type Example
0 Prefix 1 The 2-byte prefix marking the start of the frame MB_MCU_PREFIX_1 0xFF
1 Prefix 2 MB_MCU_PREFIX_2 0x55
2 Index Same with the “Index” field of the data request command Byte (0-255) 0x01
3 Data Type The data format (and length) of the data payload: float (4 bytes), short (2 bytes), double (4 bytes), long (4 bytes), string (length indicated by the next byte) MB_MCU_DATATYPE_FLOAT

MB_MCU_DATATYPE_SHORT

MB_MCU_DATATYPE_DOUBLE

MB_MCU_DATATYPE_STRING

MB_MCU_DATATYPE_LONG

 

 

 

 0x01
… Data Payload Data in the frame, length depends on Data Type.  

 

 0x01
n-1 Suffix 1 2-byte suffix marking the end of the frame MB_MCU_SUFFIX_1 0x0d
n Suffix 2 MB_MCU_SUFFIX_2 0x0a

mBot Instructions

DC Motor

begin_code_1 begin_code_2 length index action device port speed_low speed_high
ff 55 06 00 02 0a 09 ff 00

speed_low = speed & 0xff;
speed_high = (speed >> 8) & 0xff;
(“speed” is a number set by your own, ranging from -255 to 255.)

For example:

Set left DC motor speed 255:

  • ff 55 06 60 02 0a 09 ff 00

Set right DC motor speed 255:

  • ff 55 06 60 02 0a 0a ff 00

Buzzer

begin_code_1 begin_code_2 length index action device tone_Low tone_High beat_Low beat_High
ff 55 07 00 02 22 7b 00 fa 00

tone_low = tone&0xff;
tone_high = (tone>>8)&0xff;
tone is a number chosen by your own. Here is a list for you to choose the tone value:

“C2”:65, “D2”:73, “E2”:82, “F2”:87, “G2”:98, “A2”:110, “B2”:123, “C3”:131, “D3”:147, “E3”:165, “F3”:175, “G3”:196, “A3”:220, “B3”:247, “C4”:262, “D4”:294, “E4”:330, “F4”:349, “G4”:392, “A4”:440, “B4”:494, “C5”:523, “D5”:587, “E5”:658, “F5”:698, “G5”:784, “A5”:880, “B5”:988, “C6”:1047, “D6”:1175, “E6”:1319, “F6”:1397, “G6”:1568, “A6”:1760, “B6”:1976, “C7”:2093, “D7”:2349, “E7”:2637, “F7”:2794, “G7”:3136, “A7”:3520, “B7”:3951, “C8”:4186

beat_Low and beat_high have separate default values: “fa” and “00”.

For example:

Play tone C4:

  • ff 55 07 00 02 22 7b 00 fa 00

Set LED Color

begin_code_1 begin_code_2 length index action device port slot position r g b
ff 55 09 00 02 08 07 02 00 0a 00 00
position has 3 values: 01 represents left LED, 02 represents right LED, and 00 represents both LEDs.
For example:

Turn both LEDs to red color:

  • ff 55 09 00 02 08 07 02 00 0a 00 00

Read Ultrasonic Sensor Value

begin_code_1 begin_code_2 length index action device port
ff 55 04 02 01 01 03
For example:

Send data to get ultrasonic value:

  • ff 55 04 02 01 01 03

The format of data responded by the ultrasonic sensor is:

  • ff 55 02 02 23 ac 03 43 0d 0a

Please pay attention to the highlighted 4 bytes above, you should transform them from “byte” to “int” type separately, then add them together to get the result value, as follow:

  • result = ( 0x23 << 24 ) + ( 0xac << 16 ) + ( 0x03 << 8 ) + 0x43

Read Light Sensor Value

begin_code_1 begin_code_2 length index action device port
ff 55 04 05 01 03 03
For example:

Send data to get light value:

  • ff 55 04 05 01 03 03

The format of data responded by the light sensor is:

  • ff 55 05 02 00 00 40 41 0d 0a

The way to get result value is the same as the ultrasonic sensor part.

Read Line Follow Sensor

begin_code_1 begin_code_2 length index action device port
ff 55 04 60 01 11 02
For example:

Send data to get line follow sensor’s value:

  • ff 55 04 60 01 11 02

The format of data responded by the line follow sensor is:

  • ff 55 60 02 00 00 40 40 0d 0a    both led turn on
  • ff 55 60 02 00 00 00 40 0d 0a    left turn on, right turn off
  • ff 55 60 02 00 00 80 3f 0d 0a      left turn off, right turn on
  • ff 55 60 02 00 00 00 00 0d 0a      both turn off.

The line follow sensor will only return the data of the above 4 stages.

The way to get result value is the same as the ultrasonic sensor part.

Skills

Posted on

2016-03-02