Compound Pi Documentation¶

Client Installation¶

Ensure your Ubuntu client machine is connected to the same network as your Pis (whether by Ethernet or Wifi doesn’t matter). Then, execute the following to install the client and an NTP daemon:

$ sudo add-apt-repository ppa:waveform/ppa
$ sudo apt-get update
$ sudo apt-get install compoundpi-client ntp

The NTP daemon will most likely be installed to synchronize with an NTP pool on the Internet (e.g. pool.ntp.org). This is fine, but check that it’s working with the following command line:

$ ntpq -p
     remote           refid      st t when poll reach   delay   offset  jitter
==============================================================================
*aaaaaaa.aaaaaaa nn.nnn.nnn.nnn   3 u  109 1024  377    4.639   -2.101  21.233

Server Network Configuration¶

On the Pi you intend to clone, configure networking to use DHCP to automatically obtain an IP address. Edit the /etc/network/interfaces file and ensure that it looks similar to the following:

auto lo

iface lo inet loopback
iface eth0 inet dhcp

allow-hotplug wlan0
iface wlan0 inet manual
wpa-roam /etc/wpa_supplicant/wpa_supplicant.conf
iface default inet dhcp

This configuration should ensure that the first Ethernet and/or WiFi interfaces will pick up an address automatically from the local DHCP server. If you are using WiFi, complete the WiFi configuration by editing the /etc/wpa_supplicant/wpa_supplicant.conf file to look something like the following:

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1

network={
        ssid="my_wireless_ssid"
        psk="my_wireless_password"
        proto=RSN
        key_mgmt=WPA-PSK
        pairwise=CCMP
        auth_alg=OPEN
}

Server Installation¶

Execute the following command to install the Compound Pi server package and the NTP daemon (the latter is required for time-synchronized image capture):

$ sudo apt-get install compoundpi-server ntp

This should pull in all necessary dependencies, and automatically install an init-script which will start the Compound Pi daemon on boot-up. Test this by rebooting the Pi with a camera module attached. You should see the camera module’s LED light up when the daemon starts. If it doesn’t, the most likely culprit is the camera: try running raspistill, ensure you’ve activated the camera with sudo raspi-config, and ensure the CSI cable is inserted correctly. You can control the Compound Pi daemon as you would any other system daemon:

$ sudo service cpid stop
$ sudo service cpid start
$ sudo service cpid restart

Ideally, you want all your Pi servers to sync with the NTP time server you set up on your client. Edit the /etc/ntp.conf file and repalce the server lines with the IP address of your client (ideally you should configure your router to give your client a fixed address):

...
#server 0.debian.pool.ntp.org iburst
#server 1.debian.pool.ntp.org iburst
#server 2.debian.pool.ntp.org iburst
#server 3.debian.pool.ntp.org iburst
server 192.168.1.2
...

Restart the NTP daemon to use the new configuration:

$ sudo service ntp restart

Clone the SD Card¶

Once you’ve got a Pi running the Compound Pi daemon successfully, shut it down and place its SD card in any Linux machine with an SD card reader. Unmount any partitions that auto-mount, then figure out which device node represents the SD card. For example, the following would tell you that the SD card is sdd:

$ dmesg | tail | grep "Attached SCSI removable disk"
[    3.428459] sd 8:0:0:0: [sdd] Attached SCSI removable disk

Clone the SD card into a disk file:

$ sudo dd if=/dev/sdd of=server.img

This will take some considerable time to finish. Once it has done so, eject the source SD card and insert the target one in its place. Remember to unmount any partitions which auto-mount, then execute the reverse command:

$ sudo dd if=server.img of=/dev/sdd

Repeat this last step for all remaining target cards. Finally, install the SD cards in your set of Pi servers and boot them all to ensure their camera modules activate.

Testing the Servers¶

Back on the Ubuntu client machine, execute cpi to run the client. You will be presented with a command line like the following:

CompoundPi Client
Type "help" for more information, or "find" to locate Pi servers
cpi>

Firstly, ensure that the network configuration is correct. The config command can be used to print the current configuration:

cpi> config
Setting       Value
------------- --------------
network       192.168.0.0/16
port          5647
bind          0.0.0.0:5647
timeout       5
capture_delay 0
capture_count 1
video_port    False
time_delta    0.25
output        /tmp

Assuming we’re using a typical home router which gives out addresses in the 192.168.1.x network, this is incorrect. In order for broadcasts to work, the network must have the correct definition - it’s no good having a superset configured (192.168.0.0/16 is a superset of 192.168.1.0/24). To correct the network definition, use the set command:

cpi> set network 192.168.1.0/24
cpi> config
Setting       Value
------------- --------------
network       192.168.1.0/24
port          5647
bind          0.0.0.0:5647
timeout       5
capture_delay 0
capture_count 1
video_port    False
time_delta    0.25
output        /tmp

To make permanent configuration changes, simply place them in a file named ~/.cpi.ini like so:

[cpi]
network=192.168.1.0/24
timeout=10
output=~/Pictures

With the network configured correctly, you can now use find to locate your servers. If you run find on its own it will send out a broadcast ping and wait for a fixed number of seconds for servers to respond. If you know exactly how many servers you have, specify a number with the find command and it will warn you if it doesn’t find that many servers (it will also finish faster if it does find the expected number of Pis):

cpi> find 2
Found 2 servers

You can query the status of your servers with the status command which will give you the basics for the camera configuration, the time according to the server, and the number of images currently stored in memory on the server. If you only want to query a specific set of servers you can give their addresses as a parameter:

cpi> status 192.168.1.154
Address        Resolution  Time                       #
-------------- ----------- -------------------------- -
192.168.80.154 1280x720@30 2014-04-26 13:44:53.400000 0

If any major discrepancies are detected (resolution, framerate, or timestamp), the status command should notify you of them. The maximum discrepancy permitted in the timestamp is configured with the time_delta configuration setting.

To shoot an image, use the capture command:

cpi> capture

Finally, to download the captured images from all Pis, simply use the download command:

cpi> download
Downloaded image 0 from 192.168.1.154
Downloaded image 0 from 192.168.1.168

You can use the config and set commands to configure capture options, the download target directory, and so on.

Troubleshooting¶

Compound Pi provides some crude but effective tools for debugging problems. The first is simply that the daemon activates the camera by default. If you see a Pi server without the camera LED lit after boot-up, you know the daemon has failed to start for some reason.

The identify command is the main debugging tool provided by Compound Pi. If specified without any further parameters it will cause all discovered Pi servers to blink their camera LED for 5 seconds. Thus, if you run this command immediately after find you can quickly locate any Pi servers that were no discovered (typically this is due to misconfiguration of the network).

If identify is specified with one or more addresses, it will blink the LED on the specified Pi servers. This can be used to quickly figure out which address corresponds to which Pi (useful when dynamic addressing is used).

Synopsis¶

cpi [-h] [--version] [-c CONFIG] [-q] [-v] [-l FILE] [-P] [-o PATH]
    [-n NETWORK] [-p PORT] [-b ADDRESS:PORT] [-t SECS]
    [--capture-delay SECS] [--capture-count NUM] [--video-port]

Description¶

-h, --help¶

show this help message and exit

--version¶

show program’s version number and exit

-c CONFIG, --config CONFIG¶

specify a configuration file to load

-q, --quiet¶

produce less console output

-v, --verbose¶

produce more console output

-l FILE, --log-file FILE¶

log messages to the specified file

-P, --pdb¶

run under PDB (debug mode)

-o PATH, --output PATH¶

specifies the directory that downloaded images will be written to (default: /tmp)

-n NETWORK, --network NETWORK¶

specifies the network that the servers belong to (default: 192.168.0.0/16)

-p PORT, --port PORT¶

specifies the port that the servers will be listening on (default: 5647)

-b ADDRESS:PORT, --bind ADDRESS:PORT¶

specifies the address and port that the client listens on for downloads (default: 0.0.0.0:5647)

-t SECS, --timeout SECS¶

specifies the timeout (in seconds) for network transactions (default: 5)

--capture-delay SECS¶

specifies the delay (in seconds) used to synchronize captures. This must be less than the network timeout (default: 0)

--capture-count NUM¶

specifies the number of consecutive pictures to capture when requested (default: 1)

--video-port¶

if specified, use the camera’s video port for rapid capture

Usage¶

The first command in a Compound Pi session is usually find to locate the servers on the specified subnet. If you know the number of servers available, specify it as an argument to the find command which will cause the command to return quicker in the case that all servers are found, or to warn you if less than the expected number are located.

The status command can be used to check that all servers have an equivalent camera configuration, and that time sync is reasonable.

The capture command is used to cause all located servers to capture an image. After capturing, use the download command to transfer all captured images to the client.

Finally, the help command can be used to query the available commands, and to obtain help on an individual command.

Synopsis¶

cpid [-h] [--version] [-c CONFIG] [-q] [-v] [-l FILE] [-P] [-b ADDRESS]
     [-p PORT] [-d] [-u UID] [-g GID] [--pidfile FILE]

Description¶

-h, --help¶

show this help message and exit

--version¶

show program’s version number and exit

-c CONFIG, --config CONFIG¶

specify a configuration file to load

-q, --quiet¶

produce less console output

-v, --verbose¶

produce more console output

-l FILE, --log-file FILE¶

log messages to the specified file

-P, --pdb¶

run under PDB (debug mode)

-b ADDRESS, --bind ADDRESS¶

specifies the address to listen on for packets (default: 0.0.0.0)

-p PORT, --port PORT¶

specifies the UDP port for the server to listen on (default: 5647)

-d, --daemon¶

if specified, start as a background daemon

-u UID, --user UID¶

specifies the user that the daemon should run as. Defaults to the effective user (typically root)

-g GID, --group GID¶

specifies the group that the daemon should run as. Defaults to the effective group (typically root)

--pidfile FILE¶

specifies the location of the pid lock file

Usage¶

The Compound Pi server is typically started at boot time by the init service. The Raspbian package includes an init script for this purpose. Users on other platforms will need to write their own init script.

When the server starts successfully it will initialize the camera and hold it open. This will prevent other applications from using the camera but also makes it easy to see that the server has started as the camera’s LED will be lit (this is useful as Compound Pi servers are typically headless).

add¶

Syntax: add addresses

The add command is used to manually define the set of Pi’s to communicate with. Addresses can be specified individually, as a dash-separated range, or a comma-separated list of ranges and addresses.

See also: find, remove, servers.

cpi> add 192.168.0.1
cpi> add 192.168.0.1-192.168.0.10
cpi> add 192.168.0.1,192.168.0.5-192.168.0.10

capture¶

Syntax: capture [addresses]

The capture command causes the servers to capture an image. Note that this does not cause the captured images to be sent to the client. See the download command for more information.

If no addresses are specified, a broadcast message to all defined servers will be used in which case the timestamp of the captured images are likely to be extremely close together. If addresses are specified, unicast messages will be sent to each server in turn. While this is still reasonably quick there will be a measurable difference between the timestamps of the last and first captures.

See also: download, clear.

cpi> capture
cpi> capture 192.168.0.1
cpi> capture 192.168.0.50-192.168.0.53

clear¶

Syntax: clear [addresses]

The clear command can be used to clear the in-memory image store on the specified Pi servers (or all Pi servers if no address is given. The download command automatically clears the image store after successful transfers so this command is only useful in the case that the operator wants to discard images without first downloading them.

See also: download, capture.

cpi> clear
cpi> clear 192.168.0.1-192.168.0.10

config¶

Syntax: config

The config command is used to display the current client configuration. Use the related “set” command to alter the configuration.

See also: set.

cpi> config

download¶

Syntax: download [addresses]

The download command causes each server to send its captured images to the client. Servers are contacted consecutively to avoid saturating the network bandwidth. Once images are successfully downloaded from a server, they are wiped from the server.

See also: capture, clear.

cpi> download
cpi> download 192.168.0.1

exit¶

Syntax: exit|quit

The exit command is used to terminate the application. You can also use the standard UNIX Ctrl+D end of file sequence to quit.

find¶

Syntax: find [count]

The find command is typically the first command used in a client session to locate all Pi’s on the current subnet. If a count is specified, the command will display an error if the expected number of Pi’s is not located.

See also: add, remove, servers, identify.

cpi> find
cpi> find 20

framerate¶

Syntax: framerate rate [addresses]

The framerate command is used to set the capture framerate of the camera on all or some of the defined servers. The rate can be specified as an integer or floating-point number, or as a fractional value. The framerate of the camera influences the capture mode that the camera uses. See the camera hardware chapter of the picamera documentation for more information.

If no address is specified then all currently defined servers will be targetted. Multiple addresses can be specified with dash-separated ranges, comma-separated lists, or any combination of the two.

See also: status, resolution.

cpi> framerate 30
cpi> framerate 90 192.168.0.1
cpi> framerate 15 192.168.0.1-192.168.0.10

help¶

Syntax: help [command]

The ‘help’ command is used to display the help text for a command or, if no command is specified, it presents a list of all available commands along with a brief description of each.

identify¶

Syntax: identify [addresses]

The identify command can be used to locate a specific Pi server (or servers) by their address. It sends a command causing the camera’s LED to blink on and off for 5 seconds. If no addresses are specified, the command will be sent to all defined servers (this can be useful after the find command to determine whether any Pi’s failed to respond due to network issues).

See also: find.

cpi> identify
cpi> identify 192.168.0.1
cpi> identify 192.168.0.3-192.168.0.5

quit¶

Syntax: exit|quit

The exit command is used to terminate the application. You can also use the standard UNIX Ctrl+D end of file sequence to quit.

remove¶

Syntax: remove addresses

The remove command is used to remove addresses from the set of Pi’s to communicate with. Addresses can be specified individually, as a dash-separated range, or a comma-separated list of ranges and addresses.

See also: add, find, servers.

cpi> remove 192.168.0.1
cpi> remove 192.168.0.1-192.168.0.10
cpi> remove 192.168.0.1,192.168.0.5-192.168.0.10

resolution¶

Syntax: resolution width x height [addresses]

The resolution command is used to set the capture resolution of the camera on all or some of the defined servers. The resolution of the camera influences the capture mode that the camera uses. See the camera hardware chapter of the picamera documentation for more information.

If no address is specified then all currently defined servers will be targetted. Multiple addresses can be specified with dash-separated ranges, comma-separated lists, or any combination of the two.

See also: status, framerate.

cpi> resolution 640x480
cpi> resolution 1280x720 192.168.0.54
cpi> resolution 1280x720 192.168.0.1,192.168.0.3

servers¶

Syntax: servers

The servers command is used to list the set of servers that the client expects to communicate with. The content of the list can be manipulated with the find, add, and remove commands.

See also: find, add, remove.

cpi> servers

set¶

Syntax: set name value

The set command is used to alter the value of a client configuration variable. Use the related config command to view the current configuration.

See also: config.

cpi> set timeout 10
cpi> set output ~/Pictures/
cpi> set capture_count 5

status¶

Syntax: status [addresses]

The status command is used to retrieve configuration information from servers. If no addresses are specified, then all defined servers will be queried.

See also: resolution, framerate.

cpi> status

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.

BLINK¶

Syntax: BLINK

The BLINK command should cause the server to identify itself for the purpose of debugging. In this implementation, this is accomplished by blinking the camera’s LED for 5 seconds.

An OK response is expected with no data.

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.

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.

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.

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.

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

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.

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.

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

Release 0.2 (2014-04-27)¶

Several improvements in this release:

• The network protocol has been changed to enhance its reliability when dealing with lots of Pis on unreliable networks (like Wifi).
• The status command has been enhanced to warn of configuration discrepancies.
• Lots more work on the docs.

Release 0.1 (2014-04-15)¶

Initial release