LEGO Mindstorms EV3


Direct Commands

Beside running user programs the VM is able to execute direct commands from the Communication Module. In fact direct commands are small programs that consists of regular byte codes and they are executed in parallel with a running user program.
Special care MUST be taken when writing direct commands because the decision until now is NOT to restrict the use of "dangerous" codes and constructions (loops in a direct command are allowed).

If a new direct command from the same source is going to be executed an actual running direct command is terminated.

Because of a small header objects are limited to one VMTHREAD only - SUBCALLs and BLOCKs is of course not possible.
This header contains information about number of global variables (for response), number of local variables and command size.

Direct commands that has data response can place the data in the global variable space. The global variable space is equal to the communication response buffer. The composition of the direct command defines at which offset the result is placed (global variable 0 is placed at offset 0 in the buffer).

Offset in the response buffer (global variables) must be aligned (float/32bits first and 8 bits last).

  Direct 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     DIRECT_COMMAND_REPLY          0x00    //  Direct command, reply required
  #define     DIRECT_COMMAND_NO_REPLY       0x80    //  Direct command, reply not required

                                                    /*

  Byte 5 - 6: Number of global and local variables (compressed).

               Byte 6    Byte 5
              76543210  76543210
              --------  --------
              llllllgg  gggggggg

                    gg  gggggggg  Global variables [0..MAX_COMMAND_GLOBALS]

              llllll              Local variables  [0..MAX_COMMAND_LOCALS]

  Byte 7 - n: Byte codes



  Direct 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     DIRECT_REPLY                  0x02    //  Direct command reply
  #define     DIRECT_REPLY_ERROR            0x04    //  Direct command reply error

                                                    /*

  Byte 5 - n: Response buffer (global variable values)


Direct Command Examples


opOUTPUT_START Example

  Start motor connected to port A with speed 20:

        Byte codes:             opOUTPUT_POWER,LC0(0),LC0(0x01),LC0(20), opOUTPUT_START,LC0(0),LC0(0x01)
                                         \    /
                                          \  /
        Hex values send:    0C00xxxx800000A4000114A60001



opOUTPUT_STOP Example

  Stop and float motor connected to port A:

        Byte codes:             opOUTPUT_STOP,LC0(0),LC0(0x01),LC0(0),
                                         \    /
                                          \  /
        Hex values send:    0900xxxx800000A3000100



opINPUT_READ Example

  Read sensor connected to port 1:

        Byte codes:             opINPUT_READ,LC0(0),LC0(0),LC0(0),LC0(0),GV0(0),
                                         \    /
                                          \  /
        Hex values send:    0B00xxxx0001009A0000000060


        Hex values received: 0400xxxx0200
                                      ^-
                                      |
     Command global variable (response buffer offset) 0=sensor value.



opINPUT_DEVICE GET_NAME Example

  Read sensor name connected to port 1:

        Byte codes:             opINPUT_DEVICE,LC0(0),LC0(0),LC0(GET_NAME),LC0(16),GV0(0),
                                         \    /
                                          \  /
        Hex values send:    0B00xxxx001000990000151060


        Hex values received: 1300xxxx024F70656E202020202020202020202000
                                      ^-------------------------------
                                      |
     Command global variable (response buffer offset) 0..15=sensor name "Open           ".



opINPUT_DEVICE_LIST Example

  Get all device types connected to input ports:

        Byte codes:             opINPUT_DEVICE_LIST,LC0(4),GV0(0),GV0(4),
                                        \            /
                                         \    -------
                                          \  /
        Hex values send:    0900xxxx00050098046064


        Hex value received: 0800xxxx027E7E7E7D00
                                      ^---------
                                      |
    Command global variable (response buffer offset) 0=port 1 type, 1=port 2 type, 2=port 3 type, 3=port4 type, 4=change flag.



opMEMORY_WRITE Example

  Write 0x01 0x02 0x03 0x04 0x05 into global variable 4..8 of user program running in slot 1:

    opINIT_BYTES,LV0(0),LC0(5),1,2,3,4,5,
    opMEMORY_WRITE,LC0(1),LC0(0),LC0(4),LC0(5),LV0(0),

    Bytes actually sent to brick:

      1300xxxx8000142F400501020304057E0100040540
      bbbbmmmmtthhhhccccccccccccccccCCCCCCCCCCCC

      bbbb = bytes in message, mm = message counter, tt = type of command, hhhh = header, cc/CC = byte codes.

            hhhh = 10 least significant bits are number of globals, 6 most significal bits are locals


    Bytes received from brick:

      0600xxxx02
      bbbbmmmmtt

      bbbb = bytes in message, mm = message counter, tt = type of command, rr = global variables (response).



opMEMORY_READ Example

  Read global variable 4..8 from user program running in slot 1:
    opMEMORY_READ,LC0(1),LC0(0),LC0(4),LC0(5),GV0(0),

    Bytes actually sent to brick:

      0B00xxxx0005007F0100040560
      bbbbmmmmtthhhhcccccccccccc

      bbbb = bytes in message, mm = message counter, tt = type of command, hhhh = header, cc = byte codes.

            hhhh = 10 least significant bits are number of globals, 6 most significal bits are locals


    Bytes received from brick:

      0800xxxx02xxxxxxxxxx
      bbbbmmmmttrrrrrrrrrr

      bbbb = bytes in message, mm = message counter, tt = type of command, rr = global variables (response).



opINFO GET_ID Example

  Read 6 bytes ID from brick:

    opINFO,LC0(GET_ID),LC0(6),GV0(0)

    Bytes actually sent to brick:

      0900xxxx0006007C000660
      bbbbmmmmtthhhhcccccccc

      bbbb = bytes in message, mm = message counter, tt = type of command, hhhh = header, cc = byte codes.

            hhhh = 10 least significant bits are number of globals, 6 most significal bits are locals


    Bytes received from brick:

      0900xxxx02xxxxxxxxxxxx
      bbbbmmmmttrrrrrrrrrrrr

      bbbb = bytes in message, mm = message counter, tt = type of command, rr = global variables (response).



opPROGRAM_START Example

  Run app byte code file (../apps/tst/tst.rbf) in user slot (1):


    opFILE,LC0(LOAD_IMAGE),LC0(USER_SLOT),LCS,'.','.','/','a','p','p','s','/','t','s','t','/','t','s','t','.','r','b','f',0,LV0(0),LV0(4),
    opPROGRAM_START,LC0(USER_SLOT),LV0(0),LV0(4),LC0(0),

    Bytes actually sent to brick:

      2400xxxx800020C00801802E2E2F617070732F7473742F7473742E7262660040440301404400
      bbbbmmmmtthhhhccccccccccccccccccccccccccccccccccccccccccccccccccccCCCCCCCCCC

      bbbb = bytes in message, mm = message counter, tt = type of command, hhhh = header, cc/CC = byte codes.

            hhhh = 10 least significant bits are number of globals, 6 most significal bits are locals



opPROGRAM_STOP Example

  Stop program in user slot (1):

    opPROGRAM_STOP,LC0(USER_SLOT),


    Bytes actually sent to brick:

      0700xxxx8000000201
      bbbbmmmmtthhhhcccc

      bbbb = bytes in message, mm = message counter, tt = type of command, hhhh = header, cc/CC = byte codes.

            hhhh = 10 least significant bits are number of globals, 6 most significal bits are locals



LEGO® Robotics Firmware Documentation
Confidential Information © 2013 The LEGO Group