| LEGO Mindstorms EV3 |
System command are defined as: a command that's not implemented as a byte code (no VM intervention).
System Command Bytes:
,------,------,------,------,------,------,------,------,
|Byte 0|Byte 1|Byte 2|Byte 3|Byte 4|Byte 5| |Byte n|
'------'------'------'------'------'------'------'------'
Byte 0 – 1: Command size, Little Endian\n
Byte 2 – 3: Message counter, Little Endian\n
Byte 4: Command type. see following defines */
#define SYSTEM_COMMAND_REPLY 0x01 // System command, reply required
#define SYSTEM_COMMAND_NO_REPLY 0x81 // System command, reply not required
/*
Byte 5: System Command. see following defines */
#define BEGIN_DOWNLOAD 0x92 // Begin file download
#define CONTINUE_DOWNLOAD 0x93 // Continue file download
#define BEGIN_UPLOAD 0x94 // Begin file upload
#define CONTINUE_UPLOAD 0x95 // Continue file upload
#define BEGIN_GETFILE 0x96 // Begin get bytes from a file (while writing to the file)
#define CONTINUE_GETFILE 0x97 // Continue get byte from a file (while writing to the file)
#define CLOSE_FILEHANDLE 0x98 // Close file handle
#define LIST_FILES 0x99 // List files
#define CONTINUE_LIST_FILES 0x9A // Continue list files
#define CREATE_DIR 0x9B // Create directory
#define DELETE_FILE 0x9C // Delete
#define LIST_OPEN_HANDLES 0x9D // List handles
#define WRITEMAILBOX 0x9E // Write to mailbox
#define BLUETOOTHPIN 0x9F // Transfer trusted pin code to brick
#define ENTERFWUPDATE 0xA0 // Restart the brick in Firmware update mode
#define SETBUNDLEID 0xA1 // Set Bundle ID for mode2
#define SETBUNDLESEEDID 0xA2 // Set bundle seed ID for mode2
/*
Byte 6 - n: Dependent on System Command
System Command Response Bytes:
,------,------,------,------,------,------,------,------,
|Byte 0|Byte 1|Byte 2|Byte 3| | | |Byte n|
'------'------'------'------'------'------'------'------'
Byte 0 – 1: Reply size, Little Endian\n
Byte 2 – 3: Message counter, Little Endian\n
Byte 4: Reply type. see following defines */
#define SYSTEM_REPLY 0x03 // System command reply
#define SYSTEM_REPLY_ERROR 0x05 // System command reply error
/*
Byte 5: System command this is the response to
Byte 6: Reply status
*/
// SYSTEM command return codes
#define SUCCESS 0x00
#define UNKNOWN_HANDLE 0x01
#define HANDLE_NOT_READY 0x02
#define CORRUPT_FILE 0x03
#define NO_HANDLES_AVAILABLE 0x04
#define NO_PERMISSION 0x05
#define ILLEGAL_PATH 0x06
#define FILE_EXITS 0x07
#define END_OF_FILE 0x08
#define SIZE_ERROR 0x09
#define UNKNOWN_ERROR 0x0A
#define ILLEGAL_FILENAME 0x0B
#define ILLEGAL_CONNECTION 0x0C
/*
Byte 7 - n: Response dependent on System Command
The example below is build around the host application (X3 software) that wants to send a file to a P-
Brick.
,---------------------,
| c_com |
,---------> '---------------------' ------------
| |
| |
Command size, Command type, Begin/Continue D/L, File size, Filename v
^ Accept or decline, Handle
| |
| |
---- ,---------, ,---------, ,---------, <----
| USB | |Bluetooth| | WIFI |
'---------' '---------' '---------'
Command size, Command type, Begin D/L, File size, Filename ------>
<------ Command size, Command type, Handle
Command size, Command type, Continue D/L, Handle, Pay load ------>
<------ Command size, Command type
Command size, Command type, Continue D/L, Handle, Pay load ------>
<------ Command size, Command type
Command size, Command type, Continue D/L, Handle, Pay load ------>
Download strategy
-----------------
Downloading large files take time, so how to download files can be approached in 2 ways.
1) Downloading in largest possible messages i.e. using the largest command size as
possible (65534 bytes). if message size can be keept below 65534 bytes then all
data could fit into the begin download command and that would be the fastest way
to download that file. This is the fastest way to download but time is consumed
in big chunks.
2) Splitting up the file download into several messages i.e. one begin download and
several continue download commands. This will increase the download time, however
if other commands with higher priority is needed during the download these can be
interleaved between each continue download command.
This is the slowest way to download files, but leaves the possibility of interleave
other commands in between the continue download messages.
It is essential that a full message is not interrupted by other messages, that is when
the brick has received the command size (2 first bytes of a message) ALL remaining bytes
must be received as the following bytes, and the reply (from the brick) for that message
has to be received before a new message can be sent and processed in the brick.
Other download information
--------------------------
- File DownLoad
- Destination filename path is relative from "lms2012/sys"
- Destination folders are automatically created from filename path
- First folder name must be: "apps", "prjs" or "tools" (see \ref UIdesign)
- Second folder name in filename path must be equal to byte code executable name
- File Upload (File read)
- BEGIN_UPLOAD and CONTINUE_UPLOAD closes automatically the file handle when file has been uploaded
- BEGIN_GETFILE and CONTINUE_GETFILE does not close the file handle when EOF has been reached
- CONTINUE_GETFILE does also return the complete file size
- Directory upload
- LIST_FILES should work as long as list does not exceed 1014 bytes. CONTINUE_LISTFILES has NOT
been implemented yet.
- File handles
- CLOSE_FILEHANDLE is partly implemented - hash is not working
Examples:
*********************************************************************************************************
File download:
---------------
Download file "../apps/tst/tst.rbf"
BEGIN_DOWNLOAD:
Bytes sent to brick:
1C00xxxx0192xxxxxxxx2E2E2F617070732F7473742F7473742E72626600 (Hex)
bbbbmmmmttssllllllllnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn
bbbb = bytes in message, mm = message counter, tt = type of command, ss = system command,
llllllll = file length, nn.. = filename
Bytes received from brick:
0600xxxx03920000 (Hex)
bbbbmmmmttssrrhh
bbbb = bytes in message, mm = message counter, tt = type of command, ss = system command,
rr = return status, hh = handle to file
CONTINUE_DOWNLOAD:
Bytes sent to brick:
xxxxxxxx819300xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (Hex)
bbbbmmmmttsshhpppppppppppppppppppppppppppppppppppppppp
bbbb = bytes in message, mm = message counter, tt = type of command, ss = system command, hh = handle to file (from BEGIN_DOWNLOAD), pp.. = pay load
Bytes received from brick:
0600xxxx03930000 (Hex)
bbbbmmmmttssrrhh
bbbb = bytes in message, mm = message counter, tt = type of command, ss = system command,
rr = return status, hh = handle to file
File Upload:
------------
BEGIN_UPLOAD:
Bytes send to the brick:
xxxxxxxx0194xxxxxxx
bbbbmmmmttssllllnnn...
bbbb = bytes in message, mmmm = message counter, tt = type of command, ss = system command,
llll = bytes to read, nnn... = filename incl. path
Bytes received form the brick:
xxxxxxxx039400xxxxxxxx00xxx
bbbbmmmmttssrrllllllllhhppp...
bbbb = bytes in massage, mmmm = message counter, tt = type of command, ss = system command,
rr = return status, llllllll = file size, hh = file handle, ppp... = payload
CONTINUE_UPLOAD:
Bytes send to the brick:
0700xxxx019500xxxx
bbbbmmmmttsshhllll
bbbb = bytes in the message, mmmm = message counter, tt = type of command, ss = system command,
hh = file handle, llll = bytes to read
Bytes send to the PC:
xxxxxxxx03950000xxx
bbbbmmmmttssrrhhppp...
bbbb = bytes in the message, mmmm = message counter, tt = type of command, ss = system command,
rr = return status, hh = handle, pppp.. = payload
Getting file content
--------------------
Used to upload datalog files - file handle is only closed when reaching EOF and file is not
open for writing
BEGIN_GETFILE:
Bytes send to the brick:
xxxxxxxx0196xxxxxxx
bbbbmmmmttssllllnnn...
bbbb = Bytes in massage, mmmm = message counter, tt = type of command, ss = system command,
llll = max bytes to read, nnnn.... = path
Bytes send to the PC:
xxxxxxxx039600xxxxxxxx00xxx
bbbbmmmmttssrrllllllllhhppp...
bbbb = bytes ion massage, mmmm = message counter, tt = type of command, ss = system command,
rr = return status, llllllll = File size, hh = Handle, ppp... = payload
CONTINUE_GETFILE:
Bytes send to the brick:
0700xxxx019700xxxx
bbbbmmmmttsshhllll
bbbb = bytes in massage, mmmm = message counter, tt = type of command, ss = system command,
hh = handle, llll = max bytes to read
Bytes send to the PC:
xxxxxxxx039700xxxxxxxx00xxx
bbbbmmmmttssrrllllllllhhppp...
bbbb = bytes in massage, mmmm = message counter, tt = type of command, ss = system command,
rr = return status, llllllll = File size, hh = Handle, ppp... = payload
Listing files and folders:
--------------------------
LIST_FILES:
The new line delimited list is formatted as:
If it is a file:
32 chars (hex) of MD5SUM + space + 8 chars (hex) of filesize + space + filename + new line
If it is a folder:
foldername + / + new line
Bytes send to the brick:
xxxxxxxx0199xxxxxxx
bbbbmmmmttssllllnnn...
bbbb = bytes in message, mmmm = message counter, tt = type of message, ss = system command,
llll = Max bytes to read, nnn.. = path name
Bytes send to the PC:
xxxxxxxx0399xxxxxxxxxxxxxxx
bbbbmmmmttssrrllllllllhhnnn...
bbbb = bytes in message, mmmm = message counter, tt = type of message, ss = system command,
rr = return status, llllllll = List size, hh = Handle, nnn.. = new line delimited lists
CONTINUE_LIST_FILES:
Bytes send to the brick:
0700xxxx019Axxxxxx
bbbbmmmmttsshhllll
bbbb = bytes in massage, mmmm = message counter, tt = type of command, ss = system command,
hh = handle, llll = max bytes to read
Bytes send to the PC:
xxxxxxxx039Axxxxxxx
bbbbmmmmttssrrhhppp...
bbbb = bytes in massage, mmmm = message counter, tt = type of command, ss = system command,
rr = return status, hh = Handle, ppp... = payload
CLOSE_FILEHANDLE:
-----------------
Bytes send to the brick:
xxxxxxxx019800xxxxxxxxxxxxxxxx
bbbbmmmmttsshhpppppppppppppppp
bbbb = bytes in the message, mmmm = message counter, tt = type of message, ss = system command,
hh = handle, ppp... = hash
Bytes send to the PC:
0500xxxx039800
bbbbmmmmttssrr
bbbb = bytes in massage, mmmm = message counter, tt = type of message, ss = system command,
rr = return status
CREATE_DIR:
-----------
Bytes to send to the brick:
xxxxxxxx019Bxxxxxx...
bbbbmmmmttsspppppp...
bbbb = bytes in massage, mmmm = message counter, tt = type of message, ss = system command,
pp = null terminated full path of directory to create
Bytes send to the PC:
0500xxxx039Bxx
bbbbmmmmttssrr
bbbb = bytes in massage, mmmm = message counter, tt = type of message, ss = system command,
rr = return status
DELETE_FILE:
-------------
Bytes to send to the brick:
xxxxxxxx019Cxxxxxx...
bbbbmmmmttsspppppp...
bbbb = bytes in massage, mmmm = message counter, tt = type of message, ss = system command,
pp = null terminated full path of the file to delete
Bytes send to the PC:
0500xxxx039Cxx
bbbbmmmmttssrr
bbbb = bytes in massage, mmmm = message counter, tt = type of message, ss = system command,
rr = return status
LIST_OPEN_HANDLES:
----------_-------
Bytes to send to the brick:
xxxxxxxx019D
bbbbmmmmttss
bbbb = bytes in massage, mmmm = message counter, tt = type of message, ss = system command
Bytes send to the PC:
xxxxxxxx039Dxxxxxx....
bbbbmmmmttssrrpppp....
bbbb = bytes in massage, mmmm = message counter, tt = type of message, ss = system command,
rr = return status, pppp = bits indicating whether handles are busy or not.
WRITEMAILBOX:
-------------
Bytes sent to another brick:
Mailbox name has to be zero terminated but name length has to be number of chars excluding
the zero termination.
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
Reply received from another brick:
- Not valid
BLUETOOTHPIN:
--------------
This command can only be sent by USB for safety reasons
Bluetooth address does not contain colons
Bluetooth MAC address is a zero terminated string type
Bluetooth pin code is a zero terminated string type
Bytes sent to the brick:
0E00xxxx019F06xxxxxxxxxxxx04xxxx
bbbbmmmmttssllaaaaaaaaaaaaLLpppp
bbbb = bytes in the message, mmmm = message counter, tt = type of message, ss = system command,
ll = MAC Length, aaa.. = MAC address of PC, LL = Pin length, ppp... = Pin code
Bytes send to the PC:
0F00xxxx039Fxx06xxxxxxxxxxxx04xxxx
bbbbmmmmttssrrllaaaaaaaaaaaaLLpppp
bbbb = bytes in massage, mmmm = message counter, tt = type of message, ss = system command,
rr = return status, ll = MAC length, MAC address, Pin length, Pin
ENTERFWUPDATE:
--------------
This command is used to force the brick into firmware update mode. The command will not
send any response back to the host. The filesystem will not be updated when closing
Linux.
Bytes send to the brick:
0400xxxx81A0
bbbbmmmmttss
bbbb = bytes in massage, mmmm = message counter, tt = type of message, ss = system command,
SETBUNDLEID
-------------
Sets the default Bundle ID for mode2. Default bundle ID is "com.lego.lms".
xxxxxxxx01A1xxxxxx....
bbbbmmmmttsspppppp....
bbbb = bytes in massage, mmmm = message counter, tt = type of message, ss = system command,
pppppp = null terminated ID string. Max. length = 24 chars including the null termination
SETBUNDLESEEDID
------------------
Sets the default Bundle seed ID for mode2. Default bundle seed ID is "9RNK8ZF528".
xxxxxxxx01A1xxxxxx....
bbbbmmmmttsspppppp....
bbbb = bytes in massage, mmmm = message counter, tt = type of message, ss = system command,
pppppp = null terminated SEED ID string. Max. length = 11 chars including the null termination
*********************************************************************************************************