Communication Protocol

Command Type ID Codes

1 Byte will be used to indicate which type of message is being sent:

Comprehensive list of messages (by command type) that can be sent:

The station team will send all messages (except for the trigger motion plan) to mailbox 7. The robot team will respond to every message sent to mailbox 7 by copying the message into their "out" mailbox 7. This will allow the station team to confirm messages were recieved.

The required Bluetooth bytes will precede all messages (as specified by the Bluetooth format, these are the bytes that must be sent such as message length, type, mailbox, etc)

• Create Motion Plan

  - Sent from: Station -> Robot

  - Contains the Motion Plan ID and the slot to put the motion plan into on the robot

  - An error will be returned if a motion plan already exists in that slot (the user should delete the motion plan first - the station software should take care of this user path elegantly)

  - The message will then contain a series of bytes broken up into 8 bit movement commands:

      - Bits 1-3 : indicate which wheels to change speed

      - Bits  4-8 (5 bits): indicate the distance to travel (if only a single wheel is being moved it will indicate the turning degrees)

                        - Movement increments are outlined by the "Denomination System" section.

                        - Turning increments of 3 degrees with a maximum turn of 90 degrees

  Bluetooth bytes

  Command Type ID (0000 0000)

  Motion Plan ID

  Slot (0-4)

  bit 1

  bit 2

  bit 3

  bit 4

  bit 5

  bit 6

  bit 7

  bit 8

  ...

   

• Stop Motion Plan
  - Sent from: Station -> Robot
  - Only contains the stop ID
  - If no motion plan is currently executing the robot will ignore the message and send an error back

  Bluetooth bytes

  Command Type ID (0000 0001)

• Update Motion Plan

  - Sent from: Station -> Robot

  - Identical to a create motion plan except the command type indicates an update rather than a create

  - An error will be returned if the motion plan ID's do not match for the slot

  - An error will be returned if no motion plan is in that slot

  Bluetooth bytes

  Command Type ID (0000 0010)

  Motion Plan ID

  Slot (0-4)

  bit 1

  bit 2

  bit 3

  bit 4

  bit 5

  bit 6

  bit 7

  bit 8

   

• Execute Motion Plan
  - Sent from: Station -> Robot

  - Slot indicates which motion plan to execute

  - Robot will compare the Motion Plan ID sent to the motion Plan ID the robot has in that slot. If they do not match an error message will be sent and no motion plan will be executed

  - If no motion plan is in that slot an error message will be returned (and no motion plan will be executed)

  Bluetooth bytes

  Command Type ID (0000 0011)

  Motion Plan ID

  Slot (0-4)

   
• Status Update

  - Sent from: Robot -> Station

  - Return Message contains the motion plan ID and the slot of the currently executing motion plan.

    It then contains a "Step" parameter: an integer indicating which movement command the robot is executing

  Bluetooth bytes

  Command Type ID (0000 0100)

  Motion Plan ID

  Slot (0-4)

  Step

• Query Motion Plan

  - Sent from: Station -> Robot

  - Slot indicates which slot ID to query

  - The Motion Plan ID sent out is just a dummy parameter

  Bluetooth bytes

  Command Type ID (0000 0101)

  Motion Plan ID

  Slot (0-4)

   

  - Sent from: Robot-> Station

  - Return Message contains the motion plan ID and the slot it is in (Motion Plan ID will be 0 if no plan is in that slot)

  Bluetooth bytes

  Command Type ID (0000 0101)

  Motion Plan ID

  Slot (0-4)

• Adjust Motion Plan (change speed of wheels)
  - Sent from: Station -> Robot
  - Similiar structure to the "Create Motion Plan" message:

      - Byte A: indicate which wheels to change speed

      - Byte B: indicate the speed change (range from -100% to +100%)

  - An error will be returned if no motion plan is currently executing

  Bluetooth bytes

  Command Type ID (0000 0110)

  Motion Plan ID

  Slot (0-4)

  byte A

  byte B

   
• Error Message
  - Sent from: Robot -> Station
  - The Error ID will indicate what trouble the robot encountered

  Bluetooth bytes

  Command Type ID (0000 0111)

  Error ID

• Create Trigger Plan

  - Sent from: Station -> Robot

  - To create a trigger plan the station software will just send a motion plan (minus the slot ID) to mailbox 5.

  - If the robot encounters a trigger situation it will execute any motion plan stored in mailbox 5.

  Bluetooth bytes

  Command Type ID (0000 1000)

  Motion Plan ID

  bit 1

  bit 2

  bit 3

  bit 4

  bit 5

  bit 6

  bit 7

  bit 8

• *Query Trigger Plan
  - Sent from: Station -> Robot
  - Robot team puts a copy of the "Connection Lost" trigger plan in outbox 5. The station software will check outbox 5 for querying the current trigger plan.

Wheel Movement Codes (Movement Commands)

3 Bits are used to desribe which wheels should be used for an given movement command. The bit representation for this will be:

L = Left Wheel

R = Right Wheel

* There will be no movement commands that move the wheels in opposite directions.

Error Codes

1 Byte will be used to encapsulate the errors that are returned in the "Error Message"

Denomination System

Here is a potential denomination system for movements as discussed. I say "potential" because it is expected that this will be coded in such a way that changes to the system should be easy.

The binary value of "00000" has been been set to 1000cm (10m) for design reasons. The dash notation, e.g. "0-0101" has been used to enhance readability. 5 bits are used instead of 8 because the three preceding bits are the wheel code (see the section "Wheel Movement Codes").

Sample Messages

These are actively being worked out (April 6th), so if you notice anything you think is a problem, please let me know.

Create Motion Plan
byte1: 0000 0000 // command ID type: create motion plan
byte2: 0000 1001 // motion plan ID: 9
byte3: 0000 0100 // slot: 4
byte4: 000 01101 // L & R Forward, 25cm (see denom system)
byte5: 010 11100 // L Forward (turn right), 84deg (28bin * 3deg)
byte6: 000 10010 // L & R Forward, 50cm
byte7: 011 11110 // L Backward (turn left), 90deg (30bin * 3deg)
byte8: 001 10111 // L & R Back, 100cm
byte9: 0000 0000 // null terminator

The fact that a null terminator is required is specified in Appendix 2 of the Lego Mindstorms Bluetooth documentation. Further evidence is seen by this example (refer to the line which reads "byteOut(Len(TextBox1.Text) + 6) = &H0 'add null terminator").

The question is whether or not the null terminator actually arrives as part of the message in the mailbox on the robot side of things, or is it stripped off along with the rest of the Bluetooth bytes.

The bytes listed above, bytes 1 through 9, are the bytes that should arrive in the robot's mailbox. There are Bluetooth bytes that precede that, and they are as follows:

byteA = 13  // number bytes in output message (counting from byteC to byte9)
byteB = &H0  // should be 0 for NXT
byteC = &H80 // &H0 = reply expected &H80 = no reply expected
byteD = &H9  // Send Bluetooth
byteE: 7  // Box Number - 1
byteF: 9 // message size with null terminator

Bytes A through F should not be of any concern to the robot team. The complete message as written in VB 2008 appears as follows:

byteOut(0) = 13  'number bytes in output message
byteOut(1) = &H0  'should be 0 for NXT
byteOut(2) = &H80 '&H0 = reply expected &H80 = no reply expected
byteOut(3) = &H9  'Send Bluetooth message
byteOut(4) = 7  'Box Number - 1
byteOut(5) = 9  'message size with null terminator
byteOut(6) = 0 'command type: create motion plan
byteOut(7) = 9 'motion plan ID: 9
byteOut(8) = 4 'slot number: 4
byteOut(9) = &HD '000-1101 L & R Forward, 25cm (see denom system)
byteOut(10) = &H5C '010-01010  L Forward (turn right), 84deg (28bin * 3deg)
byteOut(11) = &H12 '000-10010 L & R Forward, 50cm
byteOut(12) = &H7E '011 11110 L Backward (turn left), 90deg (30bin * 3deg)
byteOut(13) = &H37 '001 10111 L & R Back, 100cm
byteOut(14) = &H0 'add null terminator
SerialPort1.Write(byteOut, 0, 15) 'send message

VB automatically handles conversions, so writing in both decimal and hexadecimal are valid (I alternated between the two representations for convenience). VB doesn't have a binary notation like it does a hexadecimal notation (marked as "&H"), which is unfortunate.