Skip to end of metadata
Go to start of metadata

Background

The EV3 has a mailbox and messaging system that allows a bluetooth device connected to the brick to exchange messages. A message has two components being a mailbox name for the message to be sent to and the message itself. The messaging system was intended to allow different EV3 bricks to communicate between each other via bluetooth however any bluetooth device can exchange messages with the brick, providing the messaging protocol has been implemented on the device.

EV3 bluetooth messaging protocol

Since the messages were intended to be used by EV3 bricks to communicate with each other, the messaging protocol is actually a system command as listed in c_com.h. The EV3 bluetooth mailbox messaging protocol can be seen under WRITEMAILBOX in c_com.h.

WRITEMAILBOX:
  -------------

    Bytes sent to another brick:

    xxxxxxxx819Exxxxxxxxxxxxxxxxxxxx
    bbbbmmmmttssllaaaaa...LLLLppp...

    bbbb = bytes in the message, mmmm = message counter, tt = type of message, ss = system command,
    ll = Name Length, aaa... = Name, LLLL = Payload length, ppp... = Payload

As an example of the messaging format, take a typical mailbox message byte stream obtained through sniffing the bluetooth connection between a brick and a connected device (byte values are in decimal). This message byte stream was generated with a mailbox name of 'abc' and a message of 'hello!'.

18    0    1    0  129  158    4   97   98   99    0    7    0  104  101  108  108  111   33    0

The breakdown of this byte stream can be seen in the table below.

Byte NumberDecimal ValueDescription

1

2

18

0

Number of bytes in the packet excluding the initial 2 bytes (little endian).

3

4

1

0

Message counter (little endian). This can be any value you wish.
5129Command type being a system command with no reply (0x81 = 129).
6158System command number for WRITEMAILBOX (0x9E = 158).
74Length of the mailbox name including zero termination character.

8

9

10

11

97

98

99

0

Mailbox name that you want the message to be sent to e.g. this value corresponds to 'abc'

12

13

7

0

Length of the message (little endian).

14

15

16

17

18

19

20

104

101

108

108

111

33

0

Message or payload e.g. this value corresponds to 'hello!'

Sending EV3 mailbox messages from the brick

The function mailBoxWrite has been implemented in Brick.m to send a mailbox message from the brick. This function has the following function definition

b.mailBoxWrite(brickname,boxname,type,msg)
% - brickname is the name of the remote device.
% - boxname is the name of the receiving mailbox.
% - type is the sent message type being either 'text', 'numeric' or 'logic'.
% - msg is the message to be sent.

The type parameter can be equal to 'text' (ASCII characters), 'numeric' (single/float precision) or 'logic' (0 or 1). The EV3 firmware allows for other data types to be used (e.g. integer) however it was decided to limit the types to the ones listed as these are the three used in the NXT-G Lego software. Note that brickname is the bluetooth device name that you want to send the mailbox message to. 

Receiving EV3 mailbox messages in MATLAB

The function readMailBox has been implemented in Brick.m to receive/parse a mailbox message from a connected EV3 brick and return the mailbox name and message. This function has the following function definition

[title,msg] = b.readMailBox(type)
% - type is the sent message type being either 'text', 'numeric' or 'logic'.
% - title is the message title sent from the brick.
% - msg is the message sent from the brick.

Note that this function is blocking and will wait until the mailbox message has been received.

Mailbox communication example

The previous two functions can be used together to send a mailbox message from the brick and have the message be received in MATLAB (running on a computer with bluetooth name 'T500').

% connect to the brick via bluetooth in windows
>> b = Brick('ioType','instrbt','btDevice','EV3','btChannel',1)
% send a 'text' mailbox message from the brick 
>> b.mailBoxWrite('T500','abc','text','hello!')
% receive the message in the MATLAB workspace
>> [title,msg] = b.readMailBox('text')
 
title = 
 
abc
 
msg = 
 
hello!

Sending mailbox messages to the brick from MATLAB

The function writeMailBox has been implemented in Brick.m to send a mailbox message from MATLAB to a connected EV3 brick. This function has the following definition

b.writeMailBox(title,type,msg)
% - title is the message title sent to the brick.
% - type is the sent message type being either 'text', 'numeric', or 'logic'.
% - msg is the message to be sent to the brick.
  • No labels