External API

Integrating Smart Shooter with an external system

Smart Shooter 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 External 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.