Vorpal Robotics Wiki
Log in

Vorpal The Hexapod Radio Protocol Technical Information

From Vorpal Robotics Wiki
Revision as of 19:22, 14 August 2017 by Vorpalwiki (talk | contribs) (Gamepad to Scratch Communication)

Vorpal Hexapod Quick Links:

Gamepad to Hexapod Communication Packet

A communication packet from the gamepad to the hexapod has the following format:

  • The literal character 'V' starts the packet.
  • The literal character '1' indicates protocol version 1.
  • A one-byte length, called L in this description. This is the length of the payload data only, it does not include the 'V1' header, the length byte, or the checksum byte.
  • The actual payload data consisting of a number of bytes equal to L.
  • A checksum byte. This is the modulo 256 sum of the length byte L and all of the payload bytes.

The payload can contain one or more commands to the hexapod. There are three different formats for these commands:

  • A 3-byte gamepad function specification, which consists of:
    • A mode letter: W, D, or F
    • A mode number: the literal characters 1, 2, 3, or 4
    • A DPAD letter: f, b, l, r, s, w.
    • For example, W2f which means that the function to execute is walk mode 2 with the forward DPAD button pressed. As such, this type of command always starts with a literal character of W, D, or F.
  • A 5-byte beep command. This command consists of:
    • Starts with the literal letter 'B'
    • A 2-byte frequency, high byte first. Frequency is only effective between about 50 and 2000 Hertz.
    • A 2-byte duration, high byte first. This is the duration of the beep in milliseconds, interpreted as an unsigned integer.
    • The robot may queue up to 32 beep commands which are played in succession in accordance with their duration.
  • A 4-byte leg motion command. This command consists of:
    • 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).
    • 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.

The payload may consist of up to 16 of these commands concatenated together.

  • A 2 byte sensor report command, consisting of:
    • The literal character 'S'
    • A 1-byte bitmask specifying which sensors the hexapod should report. Current sensors are associated with these bit positions:
      • 0 (LSB) A7
      • 1 A6
      • 2 D6/6 interpreted as an HC06 ultrasonic rangefinder
      • 3 CMUCAM5 detected object position data. CMUCAM is assumed to be attached to the ICSP header on the Hexapod Arduino Nano.

Hexapod to Gamepad Communication Packet

The hexapod only responds when it receives a sensor command (see above). Typically this sensor data is relayed by the gamepad over its serial port to be used by a Scratch X program. The format of the return data is:

  • The literal character 'V'
  • The literal character '1' which is the protocol version number
  • 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.
  • A checksum value which is a modulo 256 single byte sum of the payload bytes plus the L value.

Scratch to Gamepad Communication

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:
    • 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.

Because communication over the serial port is not error prone, there is no checksum on this protocol.

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.

Some Notes on Bluetooth Transmissions

Although the Bluetooth modules can send and receive at the same time, the SoftwareSerial Arduino library is used on both the hexapod and gamepad, and that library is unable to support simultaneous transmission and reception. For this reason, the Scratch X extension only sends data once every 100 milliseconds and the protocol sends back sensor data in the empty air time between these transmissions.

Analysis for those who are interested: The Scratch program transmission is guaranteed not to exceed 44 bytes, and at the 38,400 baud data rate that amount of data will be transmitted in about 10 milliseconds, meaning there is guaranteed to be about 90 milliseconds of clear air after a packet is sent from Scratch through the gamepad. The Hexapod is programmed to send sensor data immediately after it receives commands over Bluetooth, and this sensor data transmission completes in less than about 5 milliseconds, and so easily completes before the next set of commands are sent. This strategy ensures that neither the gamepad nor the hexapod are ever simultaneously sending and receiving Bluetooth traffic, in fact there is a quite conservative margin of error built into the protocol.

It may be possible to increase the data rate coming from Scratch (and the gamepad as well), cutting the delay time from the current 100 milliseconds to perhaps 50 to 60 milliseconds and still have an acceptable margin to avoid sends and receives from happening at the same time. In practice, most users report that the gamepad responsiveness does not feel "laggy", and it takes about 50 to 00 milliseconds for servos to move in response to most types of command anyway. There would be other considerations that would have to be tested and analysed, such as whether inexpensive SD cards could still write fast enough with this higher transmission rate (for record mode).

Also, in the current implementation, sensor data is always requested by Scratch regardless of whether the Scratch program is using it. When a Scratch program tests the value of a sensor, it is testing whatever value was most recently received. This could be changed if necessary to allow faster data rates when sensors are not being used and there is no fear of simultaneous receive/transmit operations occurring.