Vorpal The Hexapod Radio Protocol Technical Information - Revision history

Vorpalwiki: /* Gamepad to Hexapod Communication Packet */

2021-03-05T18:14:06Z

‎Gamepad to Hexapod Communication Packet

Vorpalwiki: /* Hexapod to Gamepad Communication Packet */

2021-03-04T20:52:37Z

‎Hexapod to Gamepad Communication Packet

Vorpalwiki: /* Gamepad to Scratch Communication */

2021-03-03T15:20:02Z

‎Gamepad to Scratch Communication

Vorpalwiki: /* Scratch to Gamepad Communication */

2021-03-03T15:19:14Z

‎Scratch to Gamepad Communication

Vorpalwiki: /* Gamepad to Hexapod Communication Packet */

2021-03-02T13:52:13Z

‎Gamepad to Hexapod Communication Packet

Vorpalwiki: /* Gamepad to Hexapod Communication Packet */

2021-03-02T13:49:33Z

‎Gamepad to Hexapod Communication Packet

Vorpalwiki: /* Gamepad to Hexapod Communication Packet */

2021-03-02T13:49:02Z

‎Gamepad to Hexapod Communication Packet

Vorpalwiki: /* Gamepad to Hexapod Communication Packet */

2021-03-02T13:46:50Z

‎Gamepad to Hexapod Communication Packet

Vorpalwiki: /* Trim Mode */

2020-09-10T17:44:35Z

‎Trim Mode

Vorpalwiki: /* Hexapod to Gamepad Communication Packet */

2020-09-10T17:43:01Z

‎Hexapod to Gamepad Communication Packet

@@ Line 37: / Line 37: @@
 ** The literal character 'S'
 ** Currently all sensors are sent all the time, in the future the plan is to add a bitmask option to this command to allow selective return of sensor values.
-* An 18 byte "Raw Servo" command which can set all 16 servo values or any subset of values. (Note that only the first 12 servos correspond to legs, and this command can
+* An 18 byte "Raw Servo" command which can set all 16 servo values or any subset of values. (Note that only the first 12 servos correspond to legs, and this command can therefore also set additional servos beyond the legs if desired.) The 18-byte packet consists of:
 ** The literal character 'R' (for "Raw")
 ** A 1 byte operator specification. This currently can be one of:
@@ Line 48: / Line 47: @@
 ***The special value numeric 254 meaning "put servo to sleep". This value ignores the operator specification. Power will be cut to the servo motor and it will go slack.
 ***A degree value from 0 to 180. Depending on the operator value, each servo is either set to the literal position value, has the position value added, or has the position value subtracted. If an add or subtract operation would take the servo out of the range 0 to 180 then values are clamped to the range 0 to 180.
 === Simplified Mode ===

@@ Line 90: / Line 90: @@
 * The payload length, which will be referred to as L in this section.
 * The payload bytes, of length L.
-** The payload consists of 2-byte words, high byte first, reporting sensor data as requested by the sensor command.
+** The payload consists of the literal 'S' followed by four sets of 2-byte words, high byte first, for a total of 9 bytes. These four words report sensor data as requested by the sensor command. The four words give the sensor values, in order, of A3, A6, A7, and the fully computed rangefinder distance in centimeters. See hexapod build documentation on the correct ports to hook up the rangefinder to for this to work.
 * A checksum value which is a modulo 256 single byte sum of the payload bytes plus the L value.
 Sensor data is currently hard coded to the following values (two bytes unsigned integers, high byte first)

@@ Line 121: / Line 121: @@
 == Gamepad to Scratch Communication ==
-The Gamepad simply relays any data it receives from the robot (over the Bluetooth connection) to its USB serial port for use by Scratch X programs. Right now, the only thing the robot sends back to Scratch is sensor data.
+The Gamepad simply relays any data it receives from the robot (over the Bluetooth connection) to its USB serial port for use by Scratch X programs. Right now, the only thing the robot sends back to Scratch is sensor data (see above).
 The Gamepad may also send debugging information to Scratch. Any communication from the gamepad that contains debugging messages starts with a # character, and the message continues until a newline character. Scratch will echo this data out to the developer console of the Chrome browser. If the gamepad code is compiled with any of the "debug" mode flags enabled, then these messages will become voluminous and might cause performance issues with Scratch programs.

@@ Line 108: / Line 108: @@
 A Scratch program may send two kinds of data packet to the gamepade over the serial port:
 * A normal hexapod packet, which can be any of the possible data packets that the gamepad would send to the hexapod.
-* A "record" command, which consists of:
+* A "record start" command, which consists of:
 ** The literal character 'R'
 ** The literal character '1' which is the protocol version number.
 ** A 3-byte mode button/DPAD button specification which indicates which gamepad buttons trigger the recording. For example, W1f would store the recording on the Walk mode 1 button and would be triggered when the forward DPAD button is pressed.
-** The 3-byte mode button/DPAD button specification can also be the special value 'SSS' which means stop recording.
+* A "record end" command:
 Because communication over the serial port is not error prone, there is no checksum on this protocol.

@@ Line 17: / Line 17: @@
 The payload can contain one or more commands to the hexapod. There are several different formats for these commands:
 * A 3-byte gamepad function specification, which consists of:
-** A mode letter: W, D, or F (and if running V3 software, double click modes: X, Y, Z which correspond to double click on W, D, F respectively).
+** A mode letter, literal characters from the set: W, D, or F (and if running V3 software, double click modes: X, Y, Z which correspond to double click on W, D, F respectively).
-** A mode number: the literal characters 1, 2, 3, or 4
+** A mode number: literal characters from the set: 1, 2, 3, or 4 (Note well: these are literal characters, not numeric values)
-** A D-PAD letter: f, b, l, r, s, w.
+** A D-PAD letter, literal characters from the set: f, b, l, r, s, w.
 ** For example, W2f which means that the function to execute is walk mode 2 with the forward D-PAD button pressed. As such, this type of command always starts with a literal character of W, D, or F.
-** For another example, if running V3 or later hexapod code, X3b would mean the function to execute is double-click on W3, and pressing backward D-PAD.
+** For another example, if running V3 or later hexapod code, 'X3b' would mean the function to execute is double-click on W3, and pressing backward D-PAD.
 * A 5-byte beep command. This command consists of:
 ** Starts with the literal letter 'B'
@@ Line 55: / Line 55: @@
 * The literal character ASCII '@'
 * A 3-byte gamepad function specification, which consists of:
-** A mode letter: W, D, or F (and X, Y, Z if running V3 software or later).
+** A mode letter, literal characters from the set: W, D, or F (and X, Y, Z if running V3 software or later).
-** A mode number: the literal characters 1, 2, 3, or 4
+** A mode number: literal characters from the set: 1, 2, 3, or 4
-** A D-PAD letter: f, b, l, r, s, w.
+** A D-PAD letter, literal characters from the set: f, b, l (lower case letter L), r, s, w.
-* For example, @W2f which means that the function to execute is walk mode 2 with the forward D-PAD button pressed. As such, this type of command always starts with a literal character of W, D, or F (and in V3 or later X, Y or Z as well).
+* For example, '@W2f' which means that the function to execute is walk mode 2 with the forward D-PAD button pressed. As such, this type of command always starts with a literal character of W, D, or F (and in V3 or later X, Y or Z as well).
 * For double click modes, X means a double click on a W row command, Y for a D row command, and Z for an F row command.

@@ Line 30: / Line 30: @@
 ** The literal character 'L'.
 ** The next byte is the leg selection mask, which has one bit for each leg that is affected by the command. The low bit is leg 0, the next higher bit is leg 1, etc.
-** A 1-byte bitmaks of flags. Currently, the flags may take the numeric value 0 or 1, where 0 means no flags and 1 means that hip motions should be mirrored on the left and right sides of the robot (useful for most types of walking).
+** A 1-byte bitmask of flags. Currently, the flags may take the numeric value 0 or 1, where 0 means no flags and 1 means that hip motions should be mirrored on the left and right sides of the robot (useful for most types of walking).
 ** The hip position value, from 0 to 179, followed by the knee value, from 0 to 179.
 **For either the hip or knee position, the special value 255 means no movement is required. This allows the leg motion command to move just the hips or just the knees.

@@ Line 7: / Line 7: @@
 == Gamepad to Hexapod Communication Packet ==
-A communication packet from the gamepad to the hexapod has the following format:
+A communication packet from the gamepad to the hexapod has the following format. In this discussion, literal characters are understood to be encoded in ASCII, for example literal 'V' is an eight bit byte encoded as decimal value 86.
 * The literal character 'V' starts the packet.
@@ Line 27: / Line 27: @@
 ** A 2-byte duration, high byte first. This is the duration of the beep in milliseconds, interpreted as an unsigned integer.
 ** NOTE: There is a planned enhancement in the future which would allow the robot to queue up to 32 beep commands which would be played in succession in accordance with their duration. However, currently you would have to wait between beep commands (for example when programming using scratch).
-* A 4-byte leg motion command. This command consists of:
+* A 4-byte leg motion command. This may be used to set any number of legs to servo positions of a single particular value. This command consists of:
-** The literal character L.
+** The literal character 'L'.
 ** The next byte is the leg selection mask, which has one bit for each leg that is affected by the command. The low bit is leg 0, the next higher bit is leg 1, etc.
 ** A 1-byte bitmaks of flags. Currently, the flags may take the numeric value 0 or 1, where 0 means no flags and 1 means that hip motions should be mirrored on the left and right sides of the robot (useful for most types of walking).
@@ Line 57: / Line 57: @@
 ** A mode number: the literal characters 1, 2, 3, or 4
 ** A D-PAD letter: f, b, l, r, s, w.
-* For example, @W2f which means that the function to execute is walk mode 2 with the forward D-PAD button pressed. As such, this type of command always starts with a literal character of W, D, or F.
+* For example, @W2f which means that the function to execute is walk mode 2 with the forward D-PAD button pressed. As such, this type of command always starts with a literal character of W, D, or F (and in V3 or later X, Y or Z as well).
 * For double click modes, X means a double click on a W row command, Y for a D row command, and Z for an F row command.

@@ Line 69: / Line 69: @@
 Note that there is no length or checksum. If the command letter is not a valid command then the trim packet is ignored.
 The command character can be one of these literal characters:
-*f    Raise current knee servo signal by 1 microsecond
+*f: Raise current knee servo signal by 1 microsecond
-*b    Lower current knee 1 microsecond
+*b: Lower current knee 1 microsecond
-*l    Move current hip clockwise 1 microsecond
+*l: Move current hip clockwise 1 microsecond
-*r    Move current hip counterclockwise 1 microsecond
+*r: Move current hip counterclockwise 1 microsecond
-*w    Move to next leg, the leg will twitch to indicate
+*w: Move to next leg, the leg will twitch to indicate
-*s    Do nothing, just hold steady
+*s: Do nothing, just hold steady
-*S    Save all the current trim values
+*S: Save all the current trim values
-*P    Toggle the pose between standing and adjust mode
+*P: Toggle the pose between standing and adjust mode
-*R    Show untrimmed stance in the current pose
+*R: Show untrimmed stance in the current pose
-*E    Erase all the current trim values, resetting them to 0 microseconds
+*E: Erase all the current trim values, resetting them to 0 microseconds
 When I say "microseconds" I am referring to the servo signal timing. One microsecond of signal translates to approximately one tenth of one degree of servo rotation.