External API¶

Integrating CaptureGRID with an external system

CaptureGRID can be integrated with an external system by using the External API feature. This provides two key channels of communication:

Publisher of event information
Server for handling command requests

The External API uses the ZeroMQ library for managing the communication transport layer. See http://zeromq.org for more information on how to use ZeroMQ from your system. This also defines the programming model for using the event publisher and request/reply server, as these are implementated as ZeroMQ socket endpoints.

All messages passed over the External API are encoded in JSON format. See http://json.org for more information on how to handle this type of message format.

Tip

Sample python code for the External API is available at:

https://bitbucket.org/kuvacode/smartshooter-api

Listening to Events¶

The event publisher will broadcast messages about important events that happen inside the app. This includes:

When a new photo is taken
When a photo changes state (downloaded/deleted/renamed etc)
When a new camera is detected
When a camera changes state
When a camera property changes state

Below is an example of a listener application written in Python. This can be run from the command line, and simply prints out each message that is received from the app’s publisher endpoint.

#!/usr/bin/env python3
#
# Copyright (c) 2015-2019, Kuvacode Oy
# All rights reserved. No warranty, explicit or implicit, provided.
#

import zmq

def main():
    context = zmq.Context()
    sub_address = "tcp://127.0.0.1:54543"
    sub_socket = context.socket(zmq.SUB)
    sub_socket.setsockopt(zmq.SUBSCRIBE, b"")
    sub_socket.connect(sub_address)
    print("Opened listener to: {0}".format(sub_address))
    while (True):
        raw = sub_socket.recv()
        json_msg = raw.decode("utf-8")
        print("Received: {0}".format(json_msg))

if __name__ == '__main__':
    main()

downloads/smartshooter_listen.py

For example, the text below shows the output from this after a new photo has been taken:

Opened listener to: tcp://127.0.0.1:54543
Received: {
  "msg_type": "Event",
  "msg_id": "PhotoUpdated",
  "msg_seq_num": 187,
  "msg_user_id": 0,
  "msg_result": true,
  "NetworkAddress": "192.168.1.52",
  "NetworkEndpoint": "tcp://192.168.1.52:54442",
  "PhotoSelection": "Single",
  "PhotoKey": "5752505c-07f1-4cd3-ab47-d70b4f8a5d02",
  "CameraKey": "Nikon Corporation|D5300|4337807",
  "PhotoLocation": "Local Disk",
  "PhotoOriginalName": "DSC_0000.NEF",
  "PhotoComputedName": "SSP_30.nef",
  "PhotoDateCaptured": "20190530 19:53:07.000",
  "PhotoOrigin": "ui",
  "PhotoFormat": "Raw",
  "PhotoOrientation": "None",
  "PhotoAperture": "5",
  "PhotoShutterSpeed": "1/10",
  "PhotoISO": "400",
  "PhotoFocalLength": "52.0",
  "PhotoWidth": 6000,
  "PhotoHeight": 4000,
  "PhotoFilesize": 24755185,
  "PhotoIsImage": true,
  "PhotoSequenceNum": 30,
  "PhotoBatchNum": 141,
  "PhotoHash": "095A4317"
}

Sending Requests¶

The request/reply server inside the app can handle requests to do various actions such as:

Connect/Disconnect camera
Take photo
Download/rename/delete photo
Change camera property
Auto focus camera
Change sequence/batch number

Tip

For further documentation see the public git repo:

https://bitbucket.org/kuvacode/smartshooter-api

And in particular the API documenation stored here:

https://bitbucket.org/kuvacode/smartshooter-api/src/master/external_api.rst

Configuring the External API¶

By default the External API is disabled. To enable it, go to the Network/API tab in the Options window and enable the checkbox, as shown below. This also allows customisation of the ZeroMQ endpoints that are used for the event publisher and request/reply server, so that it can be opened up for access from other computers on a network.