7. Network Protocol

The Compound Pi network protocol is UDP-based, utilizing broadcast or unicast packets for commands, and unicast packets for responses. File transfers (as initiated by the download command in the client) are TCP-based. The diagram below shows a typical conversation between a Compound Pi client and three servers involving a broadcast PING packet and the resulting responses:

All messages are encoded as ASCII text. Command messages consist of a non-zero positive integer sequence number followed by a single space, followed by the command in capital letters, optionally followed by space separated parameters for the command. The following are all valid examples of command messages:

1 PING

2 CLEAR

3 CAPTURE 1 0

4 STATUS

5 LIST

6 SEND 0 5647

7 FOO

In other words, the generic form of a command message is:

<sequence-number> <command> [parameter1] [parameter2]...

Response messages (from the servers to the client) consist of a non-zero positive integer sequence number (copied from the corresponding command), followed by a single space, followed by OK if the command’s execution was successful, optionally followed by a new-line character (ASCII character 10), and any data the response is expected to include. For example:

1 OK
VERSION 0.2

2 OK

3 OK

4 OK
RESOLUTION 1280 720
FRAMERATE 30
TIMESTAMP 1398613992.757279
IMAGES 1

5 OK
IMAGE 0 1398613992.757279 8083879

6 OK

In the case of an error, the response message consists of a non-zero positive integer sequence number (copied from the corresponding command), followed by a single space, followed by ERROR, followed by a new-line character (ASCII character 10), followed by a description of the error that occurred:

7 ERROR Unknown command FOO

In other words, the general form of a response message is:

<sequence-number> OK
<data>

Or, if an error occurred:

<sequence-number> ERROR
<error-description>

Sequence numbers start at 1 (0 is reserved), and are incremented on each command, except for ACK. The sequence number for a response indicates which command the response is associated with and likewise the sequence number for ACK indicates the response that the ACK terminates.

As UDP is an unreliable protocol, some mechanism is required to compensate for lost, unordered, or duplicated packets. An assumption is made that a Compound Pi network is more or less private, i.e. that there is little or no traffic on the network other than that generated by the Compound Pi servers and client. Hence, we assume that the network is quiescent when commands are sent by the client, so no mechanism is required for retransmitting commands.

However, responses to commands are likely to be sent more or less simultaneously by multiple Pi servers, resulting in numerous collisions and lost packets. To compensate for this, responses are retried with random delays for up to 5 seconds or until the server receives an acknowledgment from the client that the response was successfully received. The crude incrementing sequence number included in all messages guards against duplicated or unordered packets.

In the following example, the client broadcasts a PING command to three servers. The servers all respond with an OK response, but only the packet from server1 makes it back to the client. The client responds to server1 with an ACK. The other servers (after a random delay) now retry their OK responses and both get through this time. The client responds with an ACK for server3, but the ACK for server2 is lost. After another random delay, server2 once again retries its OK response, causing the client to send another ACK which succeeds this time:

The following sections document the various commands that the server understands and the expected responses.

7.1. ACK

Syntax: ACK

The ACK command is sent by the client to acknowledge receipt of a response from a server. It is special in that its sequence number must match the sequence number of the response that it acknowledges (it is the only command that does not increment the sequence number on the client).

It is also special in that its implementation is effectively optional: a client doesn’t have to acknowledge receipt of a server’s response; after 5 seconds, the server will stop retrying its responses anyway but an ACK command is nonetheless useful to reduce the congestion of the network with useless response retries.

When a server receives the ACK command, it must stop retrying responses with the same sequence number as the ACK command. No other response should be sent.

7.3. CAPTURE

Syntax: CAPTURE [count [video-port [sync]]]

The CAPTURE command should cause the server to capture one or more images from the camera. The parameters are as follows:

count
Specifies the number of images to capture. If specified, this must be a non-zero positive integer number. If not specified, defaults to 1.
video-port
Specifies which port to capture from. If unspecified, or 0, the still port should be used (resulting in the best quality capture, but may cause significant delay between multiple consecutive shots). If 1, the video port should be used.
sync
Specifies the timestamp at which the capture should be taken. The timestamp’s form is UNIX time: the number of seconds since the UNIX epoch specified as a dotted-decimal. The timestamp must be in the future, and it is important for the server’s clock to be properly synchronized in order for this functionality to operate correctly. If unspecified, the capture should be taken immediately upon receipt of the command.

The image(s) taken in response to the command should be stored locally on the server until their retrieval is requested by the SEND command. The timestamp at which the image was taken must also be stored. Storage in this implementation is simply in RAM, but implementations are free to use any storage medium they see fit.

An OK response is expected with no data.

7.4. CLEAR

Syntax: CLEAR

The CLEAR command deletes all images from the server’s local storage. As noted above in CAPTURE, implementations are free to use any storage medium, but the current implementation simply uses a list in RAM.

An OK response is expected with no data.

7.5. FRAMERATE

Syntax: FRAMERATE num[/denom]

The FRAMERATE command changes the camera’s configuration to use the specified framerate which is given either as an integer number between 1 and 90 or as a fraction consisting of an integer numerator and denominator separated by a forward-slash.

An OK response is expected with no data.

7.6. LIST

Syntax: LIST

The LIST command causes the server to respond with a new-line separated list detailing all locally stored images. Each line in the data portion of the response has the following format:

IMAGE <number> <timestamp> <size>

For example, if five images are stored on the server the data portion of the OK response may look like this:

IMAGE 0 1398618927.307944 8083879
IMAGE 1 1398619000.53127 7960423
IMAGE 2 1398619013.658935 7996156
IMAGE 3 1398619014.122921 8061197
IMAGE 4 1398619014.314919 8053651

The number portion of the line is a zero-based integer index for the image which can be used with the SEND command to retrieve the image data. The timestamp portion is in UNIX-time format: a dotted-decimal value of the number of seconds since the UNIX epoch. Finally, the size portion is an integer number indicating the number of bytes in the image.

7.7. PING

Syntax: PING

The PING command is sent by the client’s find command in order to locate Compound Pi servers. The server must send the following string in the data portion of the OK response indicating the version of the protocol that the server understands:

VERSION 0.2

Warning

As Compound Pi is a project in its infancy, the protocol version is currently the project’s version and no attempt will be made to preserve backward (or forward) compatibility in the protocol until version 1.0 is released. In the current version, the client crudely compares the version in the response with its own version and rejects anything that doesn’t match precisely.

7.8. RESOLUTION

Syntax: RESOLUTION width height

The RESOLUTION command changes the camera’s configuration to use the specified capture resolution which is two integer numbers giving the width and height of the new resolution.

An OK response is expected with no data.

7.9. SEND

Syntax: SEND index port

The SEND command causes the specified image to be sent from the server to the client. The parameters are as follows:

index
Specifies the zero-based index of the image that the client wants the server to send. This must match one of the indexes output by the LIST command.
port
Specifies the TCP port on the client that the server should connect to in order to transmit the image data. This is given as an integer number (never a service name).

Assuming index refers to a valid image index, the server must connect to the specified TCP port on the client, send the bytes of the image, and finally close the connection. The server must also send an OK response with no data.

7.10. STATUS

Syntax: STATUS

The STATUS command causes the server to send the client information about its current configuration. Specifically, the response must contain the following lines in its data portion, in the order given below:

RESOLUTION <width> <height>
FRAMERATE <num>[/denom]
TIMESTAMP <time>
IMAGES <images>

Where:

<width> <height>
Gives the camera’s currently configured capture resolution
<num>[/denom]
Gives the camera’s currently configured framerate as an integer number or fractional value
<time>
Gives the timestamp at which the STATUS command was received in UNIX time format (a dotted-decimal number of seconds since the UNIX epoch).
<images>
Gives the number of images currently stored locally by the server.

For example, the data portion of the OK response may look like the following:

RESOLUTION 1280 720
FRAMERATE 30
TIMESTAMP 1398623450.373032
IMAGES 5