Before You Get Started
RICOH’s 360 degree camera provides open API access so you can connect to the camera and build applications and devices that take advantage of camera’s low-cost, versatile 360 degree image and video capabilities. Individuals and companies in a wide range of fields are already doing this.
There are two ways to access the camera API: Over wifi and over USB.
Wifi
The RICOH THETA S 360 camera can be controlled with an API that is accessible using WiFi. Version 2 of the API is compliant with Google Open Spherical Camera API specification.
USB
An alternative to using the RICOH THETA S API over WiFi exists that works over a USB cable. This is a different API and requires firmware version 01.42 or later. v2 USB API uses extended PTP, or Picture Transfer Protocol, as the communications protocol.
There are pros and cons for using each method, depending on your specific requirements. Some of the differences are quickly highlighted here:
Getting Started with the RICOH THETA USB API
To use v2 USB API, go to:
Official RICOH THETA USB Reference v2
On the RICOH developer forum, MattWymore posted this:
I figured out how to make this work. This feature does work correctly, you just have to issue “raw”
MTP/PTP commands to get it to work. So if anybody else is using the Windows Portable Devices API
to control the Theta S, keep this in mind:
- It looks like you can’t use the WPD command
WPD_COMMAND_STILL_IMAGE_CAPTURE_INITIATE to initiate capture. If you use this
command the driver returns an error to you.
- The correct way to do this is to use
WPD_COMMAND_MTP_EXT_EXECUTE_COMMAND_WITHOUT_DATA_PHASE and set up all
the parameters and Op Code for image capture and then send that command. Take a look at this
example from Microsoft for setting things up. Basically you just need to change the Op Code to
0x100E (for initiate capture) and change the StorageID to 0x0 (as documented in the Theta v2
USB API) and you are ready to go.
Hopefully this helps out anybody that is trying to do tethered capture.
Resources
These are untested.
Windows
- Windows Dev Center, Supporting MTP Extensions (C, C++)
- WpdMtp open source project on GitHub by kon0524
Python
- PyMTP (Python bindings to LibMTP)
- python-mtp (another libmtp Python wrapper)
MTP Specification
libmtp
- libmtp on SourceForge
- installing libmtp on Ubuntu
libptp
On my system, Xenial Xerus, Ubuntu 16.04, I already had libmtp installed. I think it may be installed with Calibre ebook reader.
ricoh@xerus:~/Documents/community-document$ dpkg -l *libmtp*
Desired=Unknown/Install/Remove/Purge/Hold
| Status=Not/Inst/Conf-files/Unpacked/halF-conf/Half-inst/trig-aWait/Trig-pend
|/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad)
||/ Name Version Architecture Description
+++-==============-============-============-=================================
ii libmtp-common 1.1.10-2ubun all Media Transfer Protocol (MTP) com
ii libmtp-runtime 1.1.10-2ubun amd64 Media Transfer Protocol (MTP) run
un libmtp8 <none> <none> (no description available)
ii libmtp9:amd64 1.1.10-2ubun amd64 Media Transfer Protocol (MTP) lib
ricoh@xerus:~/Documents/community-document$
API over USB with the Raspberry Pi using Open Source libptp
From XiaomingYang
Finally got it to work. I am working on Raspberry Pi with libptp http://libptp.sourceforge.net/
I have problem with gphoto2. The problem comes from the rational number used for shutter speed in USB API. None of these package support it directly. gphoto 2.5.10 may support m15 but does not work Theta S from my test.
With ptpcam -R
, it can send a raw generic PTP request with parameters. The returned result could be reformated to shutter speed settings of Theta S. First read properties available, 0x1014 for reading device property description and 0xd00f for shutter speed. In the returned values, all the possible shutter speed is listed. For example, 01 00 00 00 a0 0f 00 are two 4-bype integers, 01 00 00 00 is 1 and a0 0f 00 00 is actually 0f a0 which is 6400.
$ ptpcam -R 0x1014,0xd00f,0,0,0,r
Camera: RICOH THETA S
Sending generic request: reqCode=0x1014, params=[0x0000d00f,0x00000000,0x00000000,0x00000000,0x00000000]
0f d0 08 00 01 00 00 00 00 00 00 00 00 01 00 00 - …
00 3c 00 00 00 02 37 00 01 00 00 00 00 19 00 00 - .<…7…
01 00 00 00 88 13 00 00 01 00 00 00 a0 0f 00 00 - …
01 00 00 00 80 0c 00 00 01 00 00 00 c4 09 00 00 - …
01 00 00 00 d0 07 00 00 01 00 00 00 40 06 00 00 - …@…
…
To get current setting of a property, 0x1015 for get property and 0xd00f for shutter speed:
$ptpcam -R 0x1015,0xd00f,0,0,0,r
Camera: RICOH THETA S
Sending generic request: reqCode=0x1015, params=[0x0000d00f,0x00000000,0x00000000,0x00000000,0x00000000]
01 00 00 00 3c 00 00 00 00 00 00 00 - …<…
PTP: response OK
The result 01 00 00 00 3c 00 00 00 could be read as (01)/(3c) = 1/60
To set shutter speed, could send binary data with ptpcam -R. To send 1/8, use 0x1016 for set property:
echo -e -n ‘\x01\x00\x00\x00\x08\x00\x00\x00’ > shutter.bin
ptpcam -R 0x1016,0x00f,0,0,0,0,shuuter.bin