SDK - Multicamera network trigger

From edgertronic high speed video camera
Revision as of 16:20, 8 March 2021 by Tfischer (talk | contribs) (Network protocol)
Jump to: navigation, search


Home

CAMAPI usage




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 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.


Replace the correct IP address of your camera in place of 10.11.12.13.

Network protocol

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

Field Default Description
Address 224.1.1.1 Any valid IP multicast address - 224.0.0.0 .. 239.255.255.255
Port 600 Any valid 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 filename parameters.

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

Example

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

 ./sctrigger.py

Produces the output:

Sending multicast packet to address 224.1.1.1 port 600 with payload 0x05AA9544

Using wireshark, the captured network packet is:

Wireshark-multicast-trigger-packet.png

Camera configuration

Configuring the camera consists of providing a multicast-trigger.conf configuration file stored on a removable storage device (SD card or USB thumbdrive) and powering on the camera. The camera will copy the multicast-trigger.conf 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 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 multicast-trigger.conf configuration file contains one section [multicast-trigger] and three keys:

Key Example
value
Legal
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

[multicast-trigger]
address = 224.1.1.1
port = 600
payload = 0x05AA9544

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, sctrigger.py, in source code format. sctrigger.py 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 sctrigger.py (leaving out command line parameter parsing) is:

    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))

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 sctrigger.py 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.

usage: sctrigger.py [-h] [-d DEBUG] [-m MULTICAST_ADDRESS] [-p PORT]  [-c COOKIE_PAYLOAD]

edgertronic endurance tests

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

Camera initiated multi-camera trigger

Using the edgertronic software extension mechanism 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 Save Link As....

File Description
multicast-trigger.conf Configuration file to enable the multicast trigger daemon built into the edgertronic camera
app_ext_multicast_trigger.py Python code suppring the 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.
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 {"payload": 95065412, "port": 600, "address": "224.1.1.1"}. 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 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
sudo route -nv add -net 224.0.0.0 -netmask 224.0.0.0 -interface en0
netstat -nr


Home

CAMAPI usage