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

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:

ByteNameDescriptionTypeExample
0Prefix 1The 2-byte prefix marking the start of the frameMB_MCU_PREFIX_10xFF
1Prefix 2MB_MCU_PREFIX_20x55
2LengthThe remaining length of this commandByte (0-255)0x04
3IndexA 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 repliesByte (0-255)0x01
4ActionRead (01) or write (02)MB_MCU_COMMAND_READ

OR

MB_MCU_COMMAND_WRITE

0x01
5DeviceType of Device (sensors or actuators)Byte (0-255)0x00
PayloadRemaining data in the frame

 

Response Data Formats

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

ByteNameDescriptionTypeExample
0Prefix 1The 2-byte prefix marking the start of the frameMB_MCU_PREFIX_10xFF
1Prefix 2MB_MCU_PREFIX_20x55
2IndexSame with the “Index” field of the data request commandByte (0-255)0x01
3Data TypeThe 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 PayloadData in the frame, length depends on Data Type. 

 

0x01
n-1Suffix 12-byte suffix marking the end of the frameMB_MCU_SUFFIX_10x0d
nSuffix 2MB_MCU_SUFFIX_20x0a

mBot Instructions

DC Motor

begin_code_1begin_code_2lengthindexactiondeviceportspeed_lowspeed_high
ff550600020a09ff00

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_1begin_code_2lengthindexactiondevicetone_Lowtone_Highbeat_Lowbeat_High
ff55070002227b00fa00

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_1begin_code_2lengthindexactiondeviceportslotpositionrgb
ff55090002080702000a0000
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_1begin_code_2lengthindexactiondeviceport
ff550402010103
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_1begin_code_2lengthindexactiondeviceport
ff550405010303
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_1begin_code_2lengthindexactiondeviceport
ff550460011102
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