View source for SDK - Multicamera network trigger

{{SDK Navigation || [[SDK - CAMAPI usage | CAMAPI usage]]}}
<div style="width:20%;height:100%;float:right;padding-left:10px;overflow-y: scroll;">
{{SDK TOC}}
</div>
<br>

= Background =

The camera supports being triggered by the receipt of a network multicast UDP packet.  This is useful when you have multiple cameras that need to be triggered close to the same time but do not need to be [[Genlock|genlocked]].  The advantage of triggering via a network multicast packet is extra cabling between the camera is not needed.  '''v2.5.1 feature''': you can include the filename in the multicast UDP packet.


{{ReplaceIP}}

= Network protocol =

The edgertronic multicast trigger network protocol is straight forward.  Only one packet is defined and the payload has 4 bytes data.

{| class="wikitable"
! Field || Default || Description
|-
| Address || 224.1.1.1 || Any valid [https://en.wikipedia.org/wiki/IP_multicast IP multicast address] - 224.0.0.0 .. 239.255.255.255
|-<
| Port || 600 || Any valid [https://en.wikipedia.org/wiki/Port_%28computer_networking%29 UDP port number] - 1 .. 65535
|-
| Payload || 0x05AA9544 || Any four byte value transmitted in network order.
|-
| Filename || none || Up to 99 character filename.  Terminate with a NULL '\0' character (C style string).  Can contain [[User_Manual_-_Filenaming#File_naming_parameters|filename parameters]].
|}

The above three values are specified in the <tt>multicast-trigger.conf</tt> configuration file as described below.

== Example ==

Send a multicast network trigger packet using the supplied python application <tt>sctrigger.py</tt> with no parameters so the default address, port, and payload value will be used:

<pre style="background:#d6e4f1">
 ./sctrigger.py
</pre>

Produces the output:
<pre style="background:#d6e4f1">
Sending multicast packet to address 224.1.1.1 port 600 with payload 0x05AA9544
</pre>

If you want to include a filename in the multicast network trigger packet:

<pre style="background:#d6e4f1">
 ./sctrigger.py "behind_home_plate_inning_1_pitch_27_&T"
</pre>

Using wireshark, the captured network packet is:

[[File:Wireshark-multicast-trigger-packet.png|800px]]

= Camera configuration =

Configuring the camera consists of providing a '''multicast-trigger.conf''' [[Configuration Files|configuration file]] stored on a removable storage device (SD card or USB thumbdrive) and powering on the camera.  The camera will copy the <tt>multicast-trigger.conf</tt> file to internal storage (micro SD card).  From that point on, each time the camera is powered on, it can be triggered by sending a well formed multicast IP packet to the camera.

The format of the configuration file complies with the [https://docs.python.org/2/library/configparser.html python configuration file format].  In summary, a python configuration file consists of sections, led by a ''[section]'' header and followed by ''name=value'' entries.

The contents of the <tt>multicast-trigger.conf</tt> configuration file contains one section '''[multicast-trigger]''' and three keys:

{| class="wikitable"
! Key || Example<br>value || Legal<br>values || description
|-
| address || 224.1.1.1 || 224.0.0.0 .. 239.255.255.255 || IP multicast address
|-
| port || 600 || 1 .. 65535 || UDP port number
|-
| payload || 0x05AA9544 || 0x00000000 .. 0xFFFFFFFF || 4 byte payload
|}

==  multicast-trigger.conf file example ==

<pre style="background:#d6e4f1">
[multicast-trigger]
address = 224.1.1.1
port = 600
payload = 0x05AA9544
</pre>

You can retrieve the above example file from the camera using the URL http://10.11.12.13/static/sdk/multicast/multicast-trigger.conf

= Example python program to trigger cameras =

The camera ships with the example python program, <tt>sctrigger.py</tt>, in source code format.  <tt>sctrigger.py</tt> showing one way to generate a multicast packet that triggers the camera.  You can find the program at  http://10.11.12.13/static/sdk/multicast/sctrigger.py

The critical portion of <tt>sctrigger.py</tt> (leaving out command line parameter parsing) is:

<pre style="background:#d6e4f1">
    import socket
    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM, socket.IPPROTO_UDP)
    sock.setsockopt(socket.IPPROTO_IP, socket.IP_MULTICAST_TTL, 32)
    print "Sending multicast packet to address %s port %d with payload %s" % (options.multicast_address, options.port, options.cookie_payload)
    ...
    sock.sendto(data, (options.multicast_address, options.port))
</pre>

A socket is created, set to send multicast packets, and then a packet is sent to the specified address and port containing the specified payload.  The <tt>sctrigger.py</tt> that can be retrieved from the camera is a full working example.

You can see the various command line options using the standard --help parameter.

<pre style="background:#d6e4f1">
usage: sctrigger.py [-h] [-d DEBUG] [-m MULTICAST_ADDRESS] [-p PORT]  [-c COOKIE_PAYLOAD] [fn]

positional arguments:
  fn                    Optional filename (max len 100). Filename can include parameters such as camera name and epoc trigger time:
                        worms_vs_caterpillars_&a_&T

optional arguments:
  -h, --help            show this help message and exit
  -d DEBUG, --debug DEBUG
                        Debug level, 0=none, 1=info, 2=debug
  -m MULTICAST_ADDRESS, --multicast_address MULTICAST_ADDRESS
                        Multicast IP address to use to trigger the camera
  -p PORT, --port PORT  Multicast IP port to use to trigger the camera
  -c COOKIE_PAYLOAD, --cookie_payload COOKIE_PAYLOAD
                        Contents of the packet data that is sent
</pre>

= Camera initiated multi-camera trigger =

Using the edgertronic software extension mechanism [[Adding python code and URLs|User Added URLs]], it is possible to create a new camera URL, that when fetched will case all the cameras on the local network to trigger.  The extension URL is http://10.11.12.13/trigger2 .  When you browse to this URL, the camera will send out a network multicast packet causing all the configured cameras to trigger, including the camera sending the multicast packet.

To configure the cameras, you need to be running camera software version 2.3.1 or newer and you need to install two files on each camera.  The two files need to be saved on each camera's SD card and then the camera is powered on to get the camera to install and use the files.

Download the files listed below by right mouse clicking on the filename and selecting <tt>Save Link As...</tt>.

{| class="wikitable"
! File !! Description
|-
|  [http://www.edgertronic.com/releases/app_ext/v2.3/multi-camera-trigger/multicast-trigger.conf multicast-trigger.conf] || Configuration file to enable the multicast trigger daemon built into the edgertronic camera
|- 
| [http://www.edgertronic.com/releases/app_ext/v2.3/multi-camera-trigger/app_ext_multicast_trigger.py app_ext_multicast_trigger.py] || Python code suppring the [[Adding python code and URLs|User Added URLs]] to create a new camera URL ''trigger2'' while when fetched causes the camera to send a multicast trigger packet to all the configured cameras on the local network.
|-
| [http://www.edgertronic.com/releases/app_ext/v2.3/multi-camera-trigger/multi-camera-install multi-camera-install] || Optional.  If you put this file on the SD card, then you can use the same SD card to install the above two files on all cameras.  Without this file, you need to resave the two files on the SD card each time you  install the files on another camera.
|}

Once the camera boots up after installed the above files, browse to http://10.11.12.13/ext to verify the application extension was installed properly.  Click on the ''/get_multicast_configuration'' to verify the multicast trigger configuration file was installed correctly.  You should see <tt>{"payload": 95065412, "port": 600, "address": "224.1.1.1"}</tt>.   Now you can browse to  http://10.11.12.13/trigger2 on any camera to cause all of the cameras to trigger.

= Limitations and comments on multicast network triggering =

* There is an unknown and variable amount of delay between when the multicast packet is sent and a camera triggers.
* Cameras receiving the multicast trigger packet will not trigger at exactly the same time.
* The multicast network trigger packet my not arrive at a camera since UDP is not a reliable transport service.  Most local area networks have very high packet delivery rates.  You can send two trigger packets to reduce the chance a camera doesn't receive a multicast network trigger packet.  You can also use CAMAPI to verify the camera triggered properly.
* If you need 100% reliable trigger and/or the ability to correlate frames captured by multiple cameras, you should use [[Trigger#External_trigger_connector|remote (wired) trigger]] and/or [[genlock]] instead of multicast network trigger.
* If you are using fixed IP addresses, then you likely need to manually add a route.  On a Mac, you can add a route via
<pre style="background:#d6e4f1">
sudo route -nv add -net 224.0.0.0 -netmask 224.0.0.0 -interface en0
netstat -nr
</pre>

{{SDK Navigation || [[SDK - CAMAPI usage | CAMAPI usage]]}}