ME218C 2021 Communication Protocol

Authors: William Alvero-Koski, Khoa Cao, Marco Nunez, Cole Paullin, Abhishek Raghunathan,
cVivian Wong

Revision History

Revision A Initial Documentation

Revision B Broadcast Packet Definition:

● Removed ‘R/W’ rows in the bit field definitions
● Changed multi-byte data arrangement to little endian
● Renamed the “Team Number” byte to “Status” and added
bit fields to show if a ship is dead or alive. Also moved the
Weapon Fired bit to here (was previously in Δx).
● Rearranged the data to utilise full bytes to allow for
additional precision
● Added a statement to clarify that a ship will be considered
dead if they fail to broadcast for more than 1 second
● Added a figure to show the linear region’s axes direction
● Changed “Zigbee protocol” to “XBee API”
● Added rule that station will be inactive after 1 second
● Added assume control bit to allow station to reassume
control after returning from a loss of internet connection

Data Packet Structure

● Intro follows MEICM standard

Revision C Communication overview

● Added a section detailing how dropped communications
should be handled
Team Packet Definition
● Clarified that Weapon fired flag is in status byte and is
now not included in Dx or Dy values

Revision D Data Packet Structure

● Updated the structure to clarify exactly the order of the
bytes to be transmitted
● Update to clarify this protocol uses little Endian
Overview
● Added how a game begins and ends
Table of Contents
Revision History
Table of Contents
Definition of Terms
Communication Overview
Gameplay Structure
Communication Interruptions
Hardware Requirements
Data Packet Structure
Zigbee Packet Definition
Broadcast Packet Definition
Team Packet Definition
Example Transmissions
Definition of Terms
Team: A team consists of all members operating one TRIAC.
TRIAC: A TRIAC is a space ship constructed by each team. A TRIAC consists of 3 stations.
Stations: There are 3 stations within each TRIAC:
● ZENER: responsible for navigation
● OPAMP: responsible for allocating energy resources between shield, weapon
and accelerating.
● TVS: responsible for the weapon.
Broadcast: A​​message​​sent​​to​​all​​radio​ ​devices​​on​​the​​network/sending​​to​​all​​devices​​on​​the
network.​​See the “Broadcast Packet Definition” section for more information.
Send: Unless​​otherwise​​specified,​​this​​shall​​refer​​to​​sending​​a​​message​​to​​a​​single​​other​​device
whose​​address​​is​​known.

Communication Overview
Communications in this game is the main way the game is implemented and are broken up into
two categories: Communication between the stations of the TRIAC and messages broadcast
from one TRIAC to all others. This document describes the protocol for both categories of
messages. From the requirements of the game, each TRIAC will broadcast a packet containing
its position at a rate of 5Hz or once every 0.2s. Each station will also send a packet to both
other stations at a rate of 5Hz. Ie every 0.2s, the ZENER will broadcast a packet and send two
packets, one to OPAMP and one to TVS. Contents of these packets are defined later in this
protocol document. ZENER is the only station that will broadcast a packet. If the TVS wants to
fire, it will send a packet to ZENER with the needed information and ZENER will include that
information in its next broadcast.

It is important to note that the data is bottlenecked on the Rx line connecting the microprocessor
to the ESP32 module. Per the specifications, that line will be at 9600 baud or 960 bytes per
second. The ZENER broadcast from each team at a rate of 5Hz will take up 600 bytes per
second of this capacity. The rest of the capacity is reserved for the station to station
communication. If too many messages are received by the ESP32 and the data transmission
rate exceeds 9600 baud, the station will not be receiving the information it needs at the correct
time. Due to the bandwidth limitations, the max number of teams able to play in a round is 7
teams.
Game Play Structure

A game begins when any TRIAC begins broadcasting its position in the Linear Region. At this
point, any other team can also begin broadcasting and join the game. Since all intra-team
communication is handled in the broadcast there should be no battles occurring unless multiple
teams are broadcasting.

A game ends when all but one team are declaring themselves dead in their broadcast.

Communication Interruptions

Dropped communications. When a ship is killed, it will continue to broadcast its position but with
the Alive/Dead flag set properly. Therefore, if you do not receive a broadcast from a team, it can
be assumed that that team has lost internet connection. This team will re-enter the battle when
their internet is re-established and the TRIAC begins broadcasting again. For team
communication, if a station is out of contact for 1 second (5 transmissions are lost) then that
station will be considered out of contact, and another station needs to assume its
responsibilities.
Hardware Requirements
Communications Hardware:

An ESP32 Internet communications module is used to implement Xbee-style communication

over a TCP/IP link. It communicates over an asynchronous serial link using a replicated, limited
Xbee API. It requires +5 V and ground to power up, which can be supplied either through a
direct 5V supply line, or through a USB connection to a computer. The module contains RxD
and Txd pins, which respectively correspond to the data input and output from the module.

Each module is pre-programmed with a 16-bit virtual address. This allows us to direct messages
to any other module by specifying the address as part of the API command. The module uses a
WiFi connection to access the IRC server in order to communicate with other modules.
Each node on each TRIAC will be equipped with an ESP32, providing it with a unique address.
This allows for stations within a team to send directed messages to each other.

Data Packet Structure

The following sections define the data packet structures to be used for communications
between the teams and internally between the stations of each team. The signal specifications
are 0V low, +3.3V high, 9600 baud, 8 data bits, no parity bit, 1 stop bit, and no flow control.

Xbee Packet definitions

Communication with the ESP32 shall follow the XBee API definition. The structures of the Xbee
transmit(TX) and Receive(RX) packets used have been outlined below. All the packets
described in the following section are contained within the RF Data section of the packet. When
the receiving XBee gets an RF packet, the information is outputted from the XBee’s UART
module to a microcontroller in the shown format.

Figure x : The Xbee TX packet

 Figure y : The Xbee RX packet

Where the:

● Length refers to the length in bytes of the frame data component.

● Checksum (“CHECKSUM”) is calculated by the running sum of bytes (“SUM”) within the
frame data component, such that it satisfies CHECKSUM = 0xFF - SUM.
● Frame data component for packet transmission and receipt must adhere to the
standards outlined below.

Packet Transmission Frame Data

Packet transmission shall follow the frame definition below:

API Identifier Frame ID Destination Address Options RF Data

(1 byte) (1 byte) (2 bytes) (1 byte) (Variable Length)

0x01 [Up to Team] MSB LSB 0x00 [Broadcast or Team Packet]

Where the:

● Frame ID is left to each individual team to manage.

● Destination address must be 0xFFFF when broadcasting.
● Options must be set to 0x00. If a team receives five “NO ACK” responses for the
broadcast packet, the broadcast packet must be sent from another station.
● RF Data consists of either a broadcast packet or a team packet, as defined below.
 Packet Receipt Frame Data

Packet receipt shall follow the frame definition below:

API Identifier Source Address RSSI Options RF Data

(1 byte) (2 bytes) (1 byte) (Variable Length)

0x81 MSB LSB [Ignored] [Ignored] [Broadcast or Team Packet]

Where the:

● RSSI and Options bytes can be ignored.

● RF Data consists of either a broadcast packet or a team packet, as defined below.
● Broadcast and team packets can be differentiated based on the length of the frame data.

Broadcast Packet Definition

As part of the communication, each spaceship is required to broadcast an information packet at
5Hz in order to participate in the game. If this message, or heartbeat, is not received by the
other participants for a period longer than 1 second, they will consider the spaceship to be
destroyed/inactive. If a spaceship broadcasts a packet with the alive/dead flag (defined below)
cleared, it will also be considered destroyed. To allow for possible internet connection failures,
spaceships are allowed to come back from inactivity and rejoin the game session. It was agreed
that all participants are of the highest honor and illegal resurrections will not occur.

Using the XBee API structure, the RF data portion of the broadcast packet will contain eleven
bytes of data with the following blocks:

Status Hull str Ship x-pos Ship x-pos Ship y-pos Ship y-pos Beam dx Beam dx Beam dy Beam dy Shield
LSB MSB LSB MSB LSB MSB LSB MSB str

Byte 0 Byte 1 Byte 2 Byte 3 Byte 4 Byte 5 Byte 6 Byte 7 Byte 8 Byte 9 Byte 10

Notice the particular arrangement of the multi-byte blocks. In order to adhere to a little endian
system (LSB first), the bytes are expected to be transmitted in increasing order.

A detailed description for each of these blocks is provided below:

 byte <0>: Status

TN<7:5> AD WF

bit 7 bit 0

bit 7-5 TN: Team number varying from 0 to 6

bit 4-2 Unimplemented: Read as ‘0’
bit 1 AD: Alive/Dead flag
1 = The ship is alive
0 = The ship is dead
bit 0 WF: Weapon fired flag
1 = weapon has been fired
0 = weapon was not fired. The user can ignore the DX and DY blocks.

byte <1>: Ship hull strength

HS<6:0>

bit 7 bit 0

bit 7-0 HS: The spaceship hull strength ranging from 0 to 100 in increments of 1GJ

byte <3:2>: Ship x-position

XP<15:0>

MSB <Byte 3> LSB <Byte 2>

bit 15 bit 0

bit 15-0 XP: The x-position of the spaceship measured from the upper left corner
(positive to the right) of the linear region ranging from 0 to 65535. Each unit
represents increments of 7.8125km (e.g.: 1 = 7.8125km, 2 = 15.625km,…, 65535
= 511,992.1875km).

Note: It is the user’s responsibility to ensure that the LSB goes out first during transmission.
Note: See Figure 1 for the reference frame axes.
 byte <5:4>: Ship y-position

YP<15:0>

MSB <Byte 5> LSB <Byte 4>

bit 15 bit 0

bit 15-0 YP: The y-position of the spaceship measured from the upper left corner
(positive down) of the linear region ranging from 0 to 65535. Each unit represents
increments of 7.8125km (e.g.: 1 = 7.8125km, 2 = 15.625km,…, 65535 =
511,992.1875km).

Note: It is the user’s responsibility to ensure that the LSB goes out first during transmission.
Note: See Figure 1 for the reference frame axes.

Figure 1: The Linear Region. The two axes, x and y, are defined as shown.

byte <7:6>: Beam ∆x

DX<15:0>

MSB <Byte 7> LSB <Byte 6>

bit 15 bit 0

bit 15-0 DX: The difference between the ship’s current x-position and the x-endpoint of
the beam vector, in increments of 7.8125km. Note that this value is signed.
 byte <9:8>: Beam ∆y

DY<15:0>

MSB <Byte 9> LSB <Byte 8>

bit 15 bit 0

bit 15-0 DY: The difference between the ship’s current y-position and the y-endpoint of
the beam vector, in increments of 7.8125km. Note that this value is signed.

The expected behaviour for the beam’s ∆x and ∆y description may follow two scenarios as
shown in Figure 2 below.

Figure 2: a) Simple scenario b) Complex scenario with beam wraparound

byte <10>: Ship shield strength

SS<7:0>

bit 7 bit 0

bit 7-0 SS: The spaceship shield strength ranging from 0 to 200 in increments of 1GJ
Team Packet Definition
Team members will send one communications packet at 5hz to each station in their team. If this
message, or heartbeat, is not received by the other stations for a period longer than 1 second,
that station will be considered to be inactive and command can be assumed by another station.
If the Zener is inactive, broadcast of location must be taken on by another station. If the original
station comes back online, the series of events are as follows. The station returning from
inactivity should have stopped transmission after 1 second of no connectivity. It should wait for
receipt of a transmission from the station that has taken on its responsibilities. The station
returning from loss of connectivity should update its data accordingly, and send an Assume
Command transmission to the station that had taken over, on the following transmission cycle it
can once again transmit as that station. The station that had filled in should stop transmitting on
behalf of the returned station upon receipt of an assume command transmission.

Each station will send data in the same format. If a station doesn’t have information to send in a
given byte, it will send that byte with all 0s. The information will be formatted and sent as
follows.

Status Hull Beam dx Beam dx Beam dy Beam dy Weapons Navigation Weapons Shield
Strength LSB MSB LSB MSB Power Power Capacity Capacity

Byte 0 Byte 1 Byte 2 Byte 3 Byte 4 Byte 5 Byte 6 Byte 7 Byte 8 Byte 9

byte <0>: Status

Assume ZENER OPAMP TVS Weapon Ship Hit

Command Fired

bit 7 bit 0
bit<7:6> Unimplemented: Read as ‘0’
bit<5> Assume Command: Indicates that command will be assumed by the station
this is transmitted from. Active high
bit <4:2> ZENER, OPAMP, TVS: bits indicate if the given transmission is coming from
that particular station. Multiple stations can be active in a given transmission. It
is important that only one station of each type be active at a time.
bit <1> Weapon Fired: High when Weapon fired.
bit <0> Ship hit: High when hit
 byte <1>: Hull Strength

HS<6:0>

bit 7 bit 0
bit 6-0 HS: The integrity of the hull in GJ. It can take on values from
0-100 GJ, 0 GJ should clear the TRIAC alive flag in the broadcast.

byte <3:2>: Beam ∆x

DX<15:0>

MSB <Byte 3> LSB <Byte 2>

bit 15 bit 0
bit 15-0 DX: The difference between the ship’s current x-position and the x-endpoint of
the beam vector, in increments of 7.8125km. Note that this value is signed.

byte <5:4>: Beam ∆y

DY<15:0>

MSB <Byte 5> LSB <Byte 4>

bit 15 bit 0
bit 15-0 DY: The difference between the ship’s current y-position and the y-endpoint of
the beam vector, in increments of 7.8125km. Note that this value is signed.

Note: See figure 1 and 2 for explanations of ∆x and ∆y.

Note: Ensure that LSB is sent first in case multi-byte variables.

byte <6>: Weapons Power

WP<6:0>

bit 7 bit 0
bit 6-0 WP: This is the Power apportioned to TVS by the OPAMP. Weapons power and
nav power can only be apportioned in increments of 1 GW, so the range of
acceptable numbers weapons power and Navigation power can take on is 0-64
GW.
 byte <7>: Navigation Power

NP<6:0>

bit 7 bit 0
bit 6-0 NP: The power apportioned to the ZENER by the OPAMP. See
note for weapons power.

byte <8>: Weapons Capacity

WC <7:0>

bit 7 bit 0
bit 7-0 WC: The energy held in the capacitor banks for the weapons. The range
of accepted values is 0-200 GJ.

byte <9>: Shield Capacity

SC<7:0>

bit 7 bit 0
Bit 6-0 SC: The integrity of the shields in GJ. It can take on values
from 0-200 GJ.
 Example Transmissions

Example Broadcast (RF data only):

If our ship is team 4, we are alive and we have fired our weapon.
Our hull strength is 100, our x-pos is 10km, y-pos is 100km, our beam delta x is 2000km, our
beam delta y is -4000km, and our shield is 150.

Status Hull str Ship x-pos Ship x-pos Ship y-pos Ship y-pos Beam dx Beam dx Beam dy Beam dy Shield
LSB MSB LSB MSB LSB MSB LSB MSB str

0b10000011 0x64 0x01 0x00 0x0C 0x00 0x00 0x01 0x00 0xFE 0x96

Example Team Message:

If this is the OPAMP sending the message, we now have 50 hull strength, 10 shield strength.
We are giving 50GW of power to Shields and and rest (14GW) of power to navigation and we do
not send any other information

Status Hull Beam dx Beam dx Beam dy Beam dy Weapons Navigation Weapons Shield
Strength LSB MSB LSB MSB Power Power Capacity Capacity

0b00001000 0x32 0x00 0x00 0x00 0x00 0x00 0x0E 0x00 0x0A