This article outlines the inner workings of the communication mechanisms used by stacks loaders and players. For a general overview of network ports used please see Device Communications.

Device to server communications

There are two layers of communications between devices and servers.

1. Loader communications facilitate the management of devices including software updates.
2. Player communications synchronises player data with a server and instructs a device what media should be downloaded and displayed.

Loader communications

Devices run a small application known as DS Loader, which downloads player software. This separation makes it easy to manage new devices and deploy new player software. The communication is primary UDP with HTTP fallback support as outlined below.

HTTP communications

When DS Loader first starts, HTTP is used. This is because UDP might be blocked.

1. DS Loader makes an HTTP connection to a server as specified in DS Settings.
2. DS Loader sends the MAC of the device and basic device info.
3. Server responds with a command - such as player software to download and execute.
4. DS Loader starts UDP communications.

UDP communications

1. UDP packet sent to server containing MAC of device and basic device info.
2. UDP packet returned to device containing a command.
3. Wait loaderCommsPeriod and repeat.

If no UDP response is returned from the server within the regular communications period, DS Loader falls back to HTTP communications.

Instant communications

After the first UDP packet has been sent to the server, the server can send commands at any point in time. This allows instant communications without maintaining a open connection that would be required for TCP/IP.

If UDP communications fail, the only opportunity for the server to communicate with the device is during the brief HTTP communications window that occurs approximately once per minute instigated by DS Loader (polling).

Example DS Loader commands

• Download and execute player software
• Instruct currently executing player to synchronise data
• Upload the currently available logs
• Upload a screenshot
• Restart DS Loader app
• Reboot the device (root needed)
• Clear all the data (including cached player software) on the device
• Upgrade DS Loader (root needed)

Security

DS Loader communications is not encrypted with TLS as this would require a battery backed clock and management of unique private keys for each device. Instead, communications is digitally signed by a private key on the server that is verified using a public key stored in the loader. Unsigned or incorrectly signed UDP or HTTP communications is ignored. This means DS Loader is not vulnerable to Man In The Middle Attacks.

Player communications

DS Loader commands the executing player to perform player communications. This command includes a URL where the player should post data. This address is typically HTTP, but HTTPS is also supported.  In response to posting the data, the server will return a HTTP redirect to a location where the player can fetch the latest sequence meta data.

In typical operation, player communications occurs once per minute. However, when DS Loader UDP communications is working correctly, the server can instruct the player to synchronise data at any point in time. Likewise, the player is able to communicate with the server at any time.

All player communications from the server are digitally signed and verified.

Blobstore communications

Media uploaded to the stacks platform is processed, named, and stored in storage buckets, such as Amazon S3 and Google Cloud Storage, then distributed in a variety of ways.

We refer to media (and other data types) as BLOBs. They are stored in Blobstores.

Content Delivery Network (CDN)

Caches at multiple edge locations serve BLOBs from the primary Blobstores. Players are provided a list of locations to download blobs. The download is simple HTTP. Resuming is supported to recover from interruptions without deletion. When complete, the MD5 is checked to ensure the data has not been corrupted or tampered with.

Peer to Peer (p2p)

In addition to using the CDN, the player periodically requests devices on the local network to send BLOBs it requires. To communicate with other players, UDP broadcast packets are used.

Simplified p2p overview

1. Peer opens a TCP server socket (ephemeral port) ready to receive BLOBs
2. Peer broadcasts BLOB requests to UDP port 9097
3. Neighbouring peers receive the broadcast and transfer zero or more requested BLOBs to peer
4. Peer selectively accepts or rejects BLOB transfers from neighbouring peers

The p2p protocol is designed to be ad-hoc and concurrent. Transfers from local peers can interrupt transfers from the CDN to maximise local traffic and minimise Internet traffic.

Chaining is supported. For example, Peer C can download from Peer B while Peer B is downloading from Peer A while Peer A is downloading from the CDN.

There are internal limits to the maximum number of uploads and downloads per peer. The protocol contains a bias that favours faster peers and avoid overloaded peers.