python_tests.adoc

Python

Sample code is available on GitHub. Additional Python examples are also available from the community. A better OSC Python library is available from Haarm-Pieter Duiker. Ulrich Rossgoderer wrote an example to download media from the command line.

I am using the Python requests library for HTTP requests. While you can use urllib2, requests is easier for mere mortals. Although I’m doing the testing on Windows 10, I am running the python scripts in a VirtualBox VM with default NAT network settings. The Python program is able to connect from the VM through the Windows 10 WiFi adapter and to the THETA S. I’m assuming that Python will work fine on Windows 10, but it’s easier for me to use Linux.

To test with Python, I first started by simply writing out individual commands in the script, similar to browser testing. I then moved the THETA API v2 commands into a library and wrote a command line tool to accept arguments and test each command.

The first step to learn the API is to grab some basic information from the camera and print it to your console.

import requests, json, pprint

def request(url_request):
    url_base = "http://192.168.1.1/osc/" # (1)
    url = url_base + url_request
    return url

def basic_info():
    protocols = [
        "state",
        "info"
    ]
    for protocol in protocols:
        print(60 * "=")
        print(protocol + " - Testing RICOH THETA API v2\n")
        url = request(protocol)
        if protocol == "info":
            req = requests.get(url)
        else:
            req = requests.post(url)
        pprint.pprint(req.json())

def main():
  basic_info()

main()

1. The IP address of the camera is always 192.168.1.1

This is what I get:

  ricoh@odapolis:~/Development/viewer$ python theta-python-test.py
  ============================================================
  state - Testing RICOH THETA API v2

  {u'fingerprint': u'FIG_0002',
   u'state': {u'_batteryState': u'disconnect',
              u'_captureStatus': u'idle',
              u'_latestFileUri': u'',
              u'_recordableTime': 0,
              u'_recordedTime': 0,
              u'batteryLevel': 0.67,
              u'sessionId': u'SID_0028',
              u'storageChanged': False}}
  ============================================================
  info - Testing RICOH THETA API v2

  {u'api': [u'/osc/info',
            u'/osc/state',
            u'/osc/checkForUpdates',
            u'/osc/commands/execute',
            u'/osc/commands/status'],
   u'endpoints': {u'httpPort': 80, u'httpUpdatesPort': 80},
   u'firmwareVersion': u'01.11',
   u'gps': False,
   u'gyro': False,
   u'manufacturer': u'RICOH',
   u'model': u'RICOH THETA S',
   u'serialNumber': u'00001221',
   u'supportUrl': u'https://theta360.com/en/support/',
   u'uptime': 3081}

Now, we want to take a picture. We’ll take a still image in this example, but it’s almost as easy to start a video capture and end it.

First you need to start a session and grab the session ID (SID).

  def startSession():
      url = request("commands/execute")
      body = json.dumps({"name": "camera.startSession",
           "parameters": {}
           })
      req = requests.post(url, data=body)
      response = req.json()
      print(60 * "=")
      print("startSession - Testing RICOH THETA API v2\n")
      pprint.pprint(response)
      sid = (response["results"]["sessionId"])
      print sid
      return sid

At this point I still think it’s cool, to output the response to the console. Also, it will give you a better idea of how to pull the sessionId or timeout values into your program. In the example above, I grab the response from the request. I then get the results key from the dictionary. The results value is another dictionary. I use the key sessionId to grab the value I need to take a picture.

My main() function now looks like this:

  def main():
      basic_info()
      sid = startSession() #grab session ID

The output of to the console looks like this:

  startSession - Testing RICOH THETA API v2

  {u'name': u'camera.startSession',
   u'results': {u'sessionId': u'SID_0029', u'timeout': 180},
   u'state': u'done'}
  SID_0029

Now, it’s the exciting part. We can take the picture!

  def takePicture(sid):
      url = request("commands/execute")
      body = json.dumps({"name": "camera.takePicture",
           "parameters": {
              "sessionId": sid
           }
           })
      req = requests.post(url, data=body)
      response = req.json()
      print(60 * "=")
      print("takePicture - Testing RICOH THETA API v2\n")
      pprint.pprint(response)

Add the function to main().

  def main():
      basic_info()
      sid = startSession() #grab session ID
      takePicture(sid) #still image

Run it and celebrate!

============================================================
takePicture - Testing RICOH THETA API v2

  {u'id': u'1',
   u'name': u'camera.takePicture',
   u'progress': {u'completion': 0.0},
   u'state': u'inProgress'}

In appendix, I included an easy example of an interface to access the Python library we’re building.