Categories
USB API

RICOH THETA USB API

The RICOH THETA USB API enables the use desktop computers or small computers under the THETA. The camera can be powered can controlled with a USB cable.

Beamo from 3i.ai with RICOH THETA Z1

Many companies use the 360 images to keep track of the status of building construction. Using custom software in the device can dramatically reduce the time required for staff to capture an entire site with dozens or hundreds of 360 pictures.

Beamo from 3i.ai

USB API Official Reference

The API reference document is freely available at:

https://api.ricoh/docs/theta-usb-api/

All RICOH THETA camera models can immediately use the USB API without developer registration.

In addition to control of the RICOH THETA, small computers can be combined with portable batteries to charge the RICOH THETA for all-day use.

In the example below, iGUIDE PLANIX specifications lists a 7 hour battery life for their system.

iGUIDE PLANIX

iGUIDE Planix has an option for a 256GB USB drive. It can also use multiple drives for even more storage.

It is also very common to use RICOH THETA cameras on flying and walking drones.

image
VTRUS drone

The images can be used to create 3D models of warehouses or buildings for status and inventory management.

3D model built with VTRUS drone

Video Tutorials

Explanation of what the RICOH THETA USB API is
Libraries and tools such as libptp that you can use to access the camera
Setting up a Raspberry with the RICOH THETA USB API
Using an x86 desktop computer to control the RICOH THETA using the USB API

Software and Usage Overview

Modified version of libptp2. This version has modifications from nickel110.

In the examples below, I changed the name of ptpcam to theta. This helps me to see the difference between the original ptpcam and the modified version. Tests were done on x86. Raspberry Pi, Jetson Nano and other ARM platforms are verified to work. If you have problems or questions, post them below.

lsb_release -a
No LSB modules are available.
Distributor ID: Ubuntu
Description: Ubuntu 21.10
Release: 21.10
Codename: impish

Get camera info

$ theta --info

THETA Device Info

Model: RICOH THETA Z1
manufacturer: Ricoh Company, Ltd.
serial number: '10010104'
device version: 2.01.0
extension ID: 0x00000006
image formats supported: 0x00000005
extension version: 0x006e

take picture

theta --capture

Initiating capture…
Object added 0x00000733
Capture completed successfully!

list files on camera

theta --list-files

Listing files…
Camera: RICOH THETA Z1
Handler: Size: Captured: name:
0x000006db: 8564075 2021-11-15 03:05 R0020012.JPG
0x000006dd: 8875279 2021-11-16 15:19 R0020013.JPG
0x000006de: 8898656 2021-11-16 15:20 R0020014.JPG

put camera to sleep

theta --set-property=0xd80e --val=0x01

Camera: RICOH THETA Z1
'UNKNOWN' is set to: 0
Changing property value to 0x01 [(null)] succeeded.

wake camera from sleep

theta --set-property=0xd80e --val=0x00

Camera: RICOH THETA Z1
'UNKNOWN' is set to: 1
Changing property value to 0x00 [(null)] succeeded.

set camera to video mode

theta --set-property=0x5013 --val=0x8002

Camera: RICOH THETA Z1
'Still Capture Mode' is set to: [Normal]
Changing property value to 0x8002 [(null)] succeeded.

start video capture

Saves video to file.

theta -R 0x101c,0,0,1
Camera: RICOH THETA Z1
Sending generic request: reqCode=0x101c, params=[0x00000000,0x00000000,0x00000001,0x00000000,0x00000000]

stop video capture

theta -R 0x1018,0xFFFFFFFF
Camera: RICOH THETA Z1

Sending generic request: reqCode=0x1018, params=[0xffffffff,0x00000000,0x00000000,0x00000000,0x00000000]

start video capture using gphoto2

gphoto2 --set-config movie=1

stop video capture using gphoto2

gphoto2 --set-config=/main/actions/opcode=0x1018,0xFFFFFFFF

Alternatives to USB API

RICOH THETA WebAPI

Summary

The USB API is a stable, mature API that is used in production by many companies. It is based on the MTP or PTP open specification.

MTP is part of the Windows Media Framework. On Linux and Mac, libptp2 and gphoto2 provide easy access.

Notable Replies

  1. Avatar for craig craig says:

    Additional info on known workarounds

    waking camera from sleep on THETA V may require a delay

    theta --reset-delay=2000  --set-property=0xD80E --val=0
    theta --reset-delay=2000  --set-property=0xD80E --val=1
    

    Or, use gphoto2

    gphoto2 --set-config=/main/other/d80e=1
    sudo gphoto2 --set-config=/main/other/d80e=0
    

    On Raspberry Pi, you may need libusb-compat-0.1.5 to build libptp

    image

    Streaming

    To stream to Linux, you need to install a modified version of libuvc.

  2. This is a great info with real-world examples. I haven’t used the USB API myself. Is there a comparison of the differences between the USB API and the WebAPI?

  3. Avatar for craig craig says:

    There is no table of differences with the API commands comparing USB and WebAPI.

    The USB API has these features over the WebAPI:

    • put camera to sleep
    • wake camera to sleep
    • switch to live streaming mode (over usb cable)
    • also, I don’t think the WebAPI can turn off the camera

    There is a workaround to turn the camera on with the USB cable.

    You should give it a try on a Raspberry Pi. It’s a nice way to work with the camera.

Continue the discussion at community.theta360.guide

Participants