February 28, 2021 THETA API WebAPI USB API BLE API UVC Support plug-ins

Summary of THETA APIs (2020 Edition)

Summary of THETA APIs (2020 Edition)

Original article published in Japanese here: https://qiita.com/mktshhr/items/d9667a5456beffdf51b9

1. Introduction

2020 was a turbulent year! For those wanting to focus on development, this article provides a summary of how to develop using the THETA API. Ample examples are provided so that you can easily try it yourself. The official specifications are summarized in the Developer Documentation. (Please see the RICOH THETA API section. You will want v2.1 information.)

Operating environment

In this article, we tested API commands in the following environment:

  • MacOS Catalina (10.15.7)
  • RICOH THETA V, Firmware ver. 3.50.1

2. THETA models and their compatible API / functions

The supported APIs / functions differ depending on the THETA model. Details are described here.

Year Model Name Web API USB API BLE API UVC Support Plugin Support
2013 RICOH THETA v1 - - - -
2014 RICOH THETA m15 v1 - - - -
2015 RICOH THETA S v2/v2.1 MTP v1.1 - HD/2K -
2016 RICOH THETA SC v2/v2.1 MTP v1.1 - - -
2017 RICOH THETA V v2.1 MTP v1.1 GATT 2K/4K ✔︎
2019 RICOH THETA Z1 v2.1 MTP v1.1 GATT 2K/4K ✔︎
2019 RICOH THETA SC2 - - -
  • BLE (Bluetooth Low Energy) of THETA V / Z1 is disabled by default. After connecting in AP mode over Wi-Fi, BLE can be enabled through the Web API (described later).
  • THETA SC2 does not officially support WebAPI / USB API, but generally it seems it can be used.

3. Types of API / Functions

3-1. Web API

In addition to the commands defined by Google’s Open Spherical Camera (OSC), many extended commands for THETA are defined. Originally, THETA did not have a screen and was supposed to be operated from a smartphone, so almost all operations can be performed via the Web API.

Web API version

WebAPI has been supported since the first THETA, but the protocol differs depending on the model. Currently, WebAPI v2.1, which is based on OSC ver. 2, is used. With the default WebAPI v2.0 on THETA models S / SC is based on OSC ver. 1, camera.startSession is required. OSC ver. 2 became the default for THETA V / Z1 (/ SC2), and it became stateless in OSC ver. 2, so camera.startSession is no longer necessary. THETA models S / SC also support v2.1, and you can switch to v2.1 by setting client_version. But if you disconnect, it will return to the default v2.

WebAPI Version Base Protocol
v1 PTP-IP base
v2 OSC ver.1 base
v2.1 OSC ver.2 base

Client Mode

Client Mode (“CL”) is available for THETA V / Z1. CL mode is a Wi-Fi connection mode that connects to a Wi-Fi router (same as the Wi-Fi connection for computers and smartphones). The default Wi-Fi connection setting for THETAs is AP mode (1: 1 connection mode). CL mode can be used by switching with the smartphone app or Web API (network type). Digest authentication is required in CL mode, and the use of some Web APIs such as BLE settings is restricted.

Shooting with WebAPI v2.1 (OSC ver. 2)

If you have THETA V or later based on WebAPI v2.1, you can shoot with the following line, so you can easily try the API. It’s in this format, just change the part of THETAYL00123456 to the serial number of your camera. Since digest authentication is used in CL mode, set the ID and password for CL mode connection with –digest. ID and password can be set with the RICOH THETA smartphone app.

% curl -X POST http://THETAYL00123456.local./osc/commands/execute --data '{"name":"camera.takePicture"}' -H 'content-type: application/json' --digest -u THETAYL00123456:00123456

3-2. USB API

Based on USB Media Transfer Protocol (MTP) v.1.1, you can use the extended USB API for THETA.

Taking a Picture Using USB API (MTP v1.1)

Install gphoto2 and try taking a picture using general MTP functions.

% brew install gphoto2

Connection confirmation

Connect the THETA to your Mac via USB in still image mode.

% gphoto2 --auto-detect
Model                          Port
USB PTP Class Camera           usb:020,010
% gphoto2 --summary
Camera summary:
Manufacturer: Ricoh Company, Ltd.

Take a picture

% gphoto2 --capture-image
New file is in location /store_00020001/DCIM/100RICOH/R0010680.JPG on the camera

Download the image

% gphoto2 --get-file /store_00020001/DCIM/100RICOH/R0010680.JPG
Saving file as R0010680.JPG

Take a Picture + Download + Delete (Batch execution)

% gphoto2 --capture-image-and-download --filename ./test.jpg
New file is in location /store_00020001/DCIM/100RICOH/R0010681.JPG on the camera
Saving file as ./test.jpg
Deleting file /store_00020001/DCIM/100RICOH/R0010681.JPG on the camera

Check the battery level

% gphoto2 --get-config=batterylevel
Label: Battery Level
Readonly: 1
Type: TEXT
Current: 100%

3-3. BLE API

The BLE API for Bluetooth Low Energy is an API that is uniquely service-defined for THETA based on the GATT of the Bluetooth SIG. GATT is a profile that defines the basic data transfer method of Bluetooth LE, and consists of services and attributes (Characteristic). It is basic to read and write the value of this attribute (state or command).

THETA operates as a BLE Peripheral (Advertise side), and when creating an application that connects to BLE, you will create Central (Scan side) software.

Services provided

The services defined by THETA are as follows. All services and attributes are listed here.

Service UUID Function
Camera Information 9A5ED1C5-74CC-4C50-B5B6-66A48E7CCFF1 Get camera information such as firmware version
Camera Status Command 8AF982B1-F1FF-4D49-83F0-A56DB4C431A7 Get camera status such as battery information
Camera Control Command 32886D39-BA23-425C-BCAE-9C1DB0066922 Get camera settings information such as volume
Shooting Status Command 9AD04FDF-E62B-43E4-8593-7631FCD29874 Get camera shooting status such as shooting error
Shooting Control Command 1D0F3602-8DFB-4340-9045-513040DAD991 Camera shooting process
Shooting Control Command v2 38EF1533-B0CC-4722-B6B6-8B23C27ECE5C Aperture settings, etc. Camera shooting processing added in Z1 and V Firm ver. 3 or later
GPS Control Command 84A0DD62-E8AA-4D0F-91DB-819B6724C69E Set location information on the camera
WLAN Control Command F37F568F-9071-445D-A938-5441F2E82399 Camera Wi-Fi settings
Bluetooth Control Command 0F291746-0C80-4726-87A7-3C501FD3B4B6 Camera Bluetooth settings

Connection with BLE

To enable BLE, it is necessary to connect in AP mode and prepare using WebAPI. Make a Wi-Fi connection (1: 1 Wi-Fi connection between THETA and computer) in AP mode, and enable BLE by following the steps below.

  1. Registration of BLE password

Set your own password with camera._set BluetoothDevice of Web API. Here, set the character string (“50BC9100-F957-4EC2-BBDF-196D6561A7BF”) generated by the uuidgen command.

% uuidgen

% curl -X POST --data '{"name":"camera._setBluetoothDevice","parameters":{"uuid":"50BC9100-F957-4EC2-BBDF-196D6561A7BF"}}' -H 'content-type: application/json'

  1. Set _bluetoothPower to ON
% curl -X POST --data '{"name":"camera.setOptions","parameters":{"options":{"_bluetoothPower":"ON"}}}' -H 'content-type: application/json'
  1. Connect with BLE

To check the connection with BLE, use Apple’s Bluetooth Explorer or the BLExplr app on the iPhone. These apps are convenient because they can also be used for debugging when creating BLE apps. Bluetooth Explorer is an app that runs on macOS and is included when you download the Additional Tools for XCode from the Apple Developer Connection (ADC) site. ADC developer registration is required to download. The following is an example using Bluetooth Explorer.

Start Bluetooth Explorer, select “Low Energy Devices” from the “Devices” menu, and THETA will be displayed by serial number. Select this serial number and “Connect” to display the service list described above.

low energy devices

  1. Enable BLE API

Authenticate on BLE using your own password registered earlier with WebAPI (_setBluetoothDevice). For authentication, use the Auth Bluetooth Device (EBAFB2F0-0E0F-40A2-A84F-E2F098DC13C3) in the Bluetooth Control Command service (0F291746-0C80-4726-87A7-3C501FD3B4B6). You can enable the BLE API by writing your own password here. In Bluetooth Explorer, select Characteristic of EBAFB2F0-0E0F-40A2-A84F-E2F098DC13C3 and set the password (“50BC9100-F957-4EC2-BBDF-196D6561A7BF”) set earlier in “UTF8” (“Write”). The BLE connection will be enabled, and the actual value will be displayed in the part where “Value” was displayed until then. This activation is required every time a BLE connection is made.


Taking a Picture with BLE API

Try taking a picture using the BLE API. In the Shooting Control Command service (1D0F3602-8DFB-4340-9045-513040DAD991), there is a Take Picture attribute (FEC1805C-8905-4477-B862-BA5E447528A5). If you set “1” to “RAW” (“WRITE”) here, shooting will be performed.


3-4. UVC compatible

Although it is not an API, UVC is often used as part of the system, so I will describe it a little here. UVC can be used with THETA S / V / Z1, but the version that can be used differs depending on the model and settings. Since THETA V / Z1 output images from the camera in Equirectangular format, the Dual Fish Blender required for Equirectangular output in THETA S is no longer necessary. However, RICOH THETA UVC 4K is distributed because it may not work well with apps that handle UVC.

</tr> </table> Since UVC ver. 1.5, the definition of Video Frame Descriptor now includes formats used in high-resolution videos such as H.264 / VP8, but in ver. 1.1 they are not defined and are mainly uncompressed and MJPEG was used. UVC ver. 1.5 became available on Windows 10 (ver. 1703) and macOS (10.12.4) around the fall of 2017 when THETA V was released. Regarding UVC ver. 1.5 support on Ubuntu, [libuvc for RICOH THETA](https://topics.theta360.com/en/news/2020-07-28/) was released in the summer of 2020, and its utilization is discussed in the [latter half of this topic on the theta360.guide](https://community.theta360.guide/t/live-streaming-over-usb-on-ubuntu-and-linux-nvidia-jetson/4359/25). ## 3-5. Plugin support THETA V / Z1 is based on Android OS, and you can develop and install apps which are known as “plug-ins.” Since there are many other articles that cover these topics in detail, I will omit any explanation here. But the above Web API can be executed almost as-is as communication addressed to localhost from within the plug-in. The shooting application (com.theta360.receptor) is resident in the camera and accepts Web API. ## 4. Summary In this article, I reconfirmed the specifications of the previous THETA models and their corresponding APIs. In particular, there was not much information on how to use the BLE API, so I covered the BLE API and picture taking. However, of the various APIs, the Web API is the easiest to use. If you can use WebAPI, I think it is probably a good decision. If you use CL mode, you don't need to change the Wi-Fi settings, so you can communicate using Web API with curl commands, etc. which relatively easily from Windows and Mac. Since the BLE API can be used without external connection settings, it can be used in environments where W-Fi cannot be used. Wired connections may also be available using an adapter, but if you want to perform reliable wired communication, the USB API is also an option. It's a good idea to choose an API that suits your needs.

Model UVC version Reference
RICOH THETA S v1.1(720p@15fps/MotionJPEG)

v1.5(FHD@30fps/H.264) </td>

Dual Fisheye output. Dual Fisheye Blender is required for output in Equirectangular and when using FHD.
RICOH THETA V v1.5 (FHD or 4K @30fps/H.264) Equirectangular output
RICOH THETA Z1 v1.5 (FHD or 4K @30fps/H.264) Equirectangular output