Summary of THETA APIs (2020 Edition)
Original article published in Japanese here: THETA関連APIのまとめ(2022年11月更新版) - Qiita
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.
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.
Model: RICOH THETA V
...
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%
END
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.
- 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
50BC9100-F957-4EC2-BBDF-196D6561A7BF
% curl -X POST 192.168.1.1/osc/commands/execute --data '{"name":"camera._setBluetoothDevice","parameters":{"uuid":"50BC9100-F957-4EC2-BBDF-196D6561A7BF"}}' -H 'content-type: application/json'
{"name":"camera._setBluetoothDevice","results":{"deviceName":"00129704"},"state":"done"}
- Set _bluetoothPower to ON
% curl -X POST 192.168.1.1/osc/commands/execute --data '{"name":"camera.setOptions","parameters":{"options":{"_bluetoothPower":"ON"}}}' -H 'content-type: application/json'
{"name":"camera.setOptions","state":"done"}
- 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.
- 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.
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) |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|