MacOS and RICOH THETA USB API

Originally published at: MACOS and RICOH THETA USB API - RICOH THETA Developer Community

The USB API is very popular with RICOH THETA cameras for use cases such as time lapse or high volume pictures with a device such as a Raspberry Pi. Although most people use the USB API from Linux, it is also possible to use it from the MacOS.

The main reason people use the USB API on Linux is due to the lower cost of hardware such as the Raspberry Pi or Jetson Nano. If you are comfortable using Linux, you may find more community support and examples for using the RICOH THETA USB API on Linux.

This article covers two different free and open source applications that run on MacOS that can configure the USB API of RICOH THETA cameras.

  • gphoto2
  • ptpcam

gphoto2 Installation on MacOS using brew

You can easily install gphoto2 on a Mac with

brew install gphoto2

If you do not have brew installed on your Mac, see this site:

https://brew.sh/

Basic gphoto2 commands

If you run gphoto2 with no command, you can see the options.

Getting Summary Information on THETA Z1

On your Mac use gphoto2 --summary

List Files on THETA

gphoto2 --list-files

Set shutter volume

Download Files from RICOH THETA To Your Mac

Viewing Images on Mac

Take Still Image

craig@craigs-air ~ % gphoto2 --capture-image
New file is in location /store_00020001/DCIM/101RICOH/R0020127.JPG on the camera
craig@craigs-air ~ % 

Capture Image and Download

This will delete the file from the RICOH THETA camera after downloading to your Mac.

gphoto2 --capture-image-and-download
New file is in location /store_00020001/DCIM/101RICOH/R0020128.JPG on the camera
Saving file as R0020128.JPG
Deleting file /store_00020001/DCIM/101RICOH/R0020128.JPG on the camera
craig@craigs-air Documents % 

Verify download with RICOH THETA desktop application for Mac.

Get Battery Level of RICOH THETA Z1

gphoto2 --get-config=batterylevel
Label: Battery Level                                                           
Readonly: 1
Type: TEXT
Current: 100%
END
craig@craigs-air Documents % 

Get White Balance

 % gphoto2 --get-config=whitebalance
Label: WhiteBalance                                                            
Readonly: 0
Type: RADIO
Current: Automatic
Choice: 0 Automatic

Get Capture Mode

 gphoto2 --get-config=capturemode 
Label: Still Capture Mode                                                      
Readonly: 0
Type: RADIO
Current: Unknown value 8002
Choice: 0 Single Shot
Choice: 1 Timelapse

Show Info on Specific Image in RICOH THETA Camera

gphoto2 --show-info 1             
Information on file 'R0020117.JPG' (folder '/store_00020001/DCIM/101RICOH'):   
File:
  Mime type:   'image/jpeg'
  Size:        8076696 byte(s)
  Width:       6720 pixel(s)
  Height:      3360 pixel(s)
  Permissions: read/delete
  Time:        Tue Apr 26 09:09:08 2022
Thumbnail:
  Mime type:   'image/jpeg'
  Size:        10724 byte(s)
  Width:       320 pixel(s)
  Height:      160 pixel(s)
Audio data:
  None available.

Put RICOH THETA to Sleep

% gphoto2 --set-config=/main/other/d80e=1

Wake RICOH THETA Camera From Sleep

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

Set ExposureProgram to Manual

gphoto2 –set-config=500e=1    

Get ISO

With Exposure Program set to Manual.

gphoto2 --get-config /main/imgsettings/iso
Label: ISO Speed                                                               
Readonly: 0
Type: RADIO
Current: 100
Choice: 0 80
Choice: 1 100
Choice: 2 125
Choice: 3 160
Choice: 4 200
Choice: 5 250
Choice: 6 320
Choice: 7 400
Choice: 8 500
Choice: 9 640
Choice: 10 800
Choice: 11 1000
Choice: 12 1250
Choice: 13 1600
Choice: 14 2000
Choice: 15 2500
Choice: 16 3200

Set ISO to 6400

Set Mode to Video

gphoto2 --get-config=5013  
Label: Still Capture Mode                                                      
Readonly: 0
Type: MENU
Current: 32772
Choice: 0 1
Choice: 1 3
Choice: 2 32770
Choice: 3 32771
Choice: 4 32772
Choice: 5 32773
Choice: 6 32774
Choice: 7 32775
END
craig@craigs-air Documents % gphoto2 --set-config=5013=2

Alternative to gphoto2 – libptp2

libptp2 is an alternative to gphoto2 and more popular on Linux for accessing the RICOH THETA USB API.

You can install libptp2 v1.1.10 using MacPorts.

https://ports.macports.org/port/libptp2/

Information on installing MacPorts is available here:

https://www.macports.org/install.php

I’m using Monterey.

Get Camera Info with ptpcam

Set GPS Information with ptpcam

ptpcam --set-property=0xD801 --val="23.532000,23.532000+999.00m@20210904T170429.0+0900,WGS84"

Camera: RICOH THETA Z1
‘UNKNOWN’ is set to: “23.532000,23.532000+999.00m@20210904T080429,WGS84”
Changing property value to 23.532000,23.532000+999.00m@20210904T170429.0+0900,WGS84 [(null)] succeeded.
craig@craigs-air tmp %

Show GPS Setting with ptpcam

ptpcam --show-property=0xd801

Camera: RICOH THETA Z1
‘UNKNOWN’ is set to: “23.532000,23.532000+999.00m@20210904T080429,WGS84”
craig@craigs-air tmp %

Set RICOH THETA to Video Mode with ptpcam

List Files with ptpcam

Set Time Lapse to 10

craig@craigs-air tmp % ptpcam --set-property=0x501A --val=10  

Camera: RICOH THETA Z1
‘Timelapse Number’ is set to: 0
Changing property value to 10 [(null)] succeeded.
craig@craigs-air tmp %

API Reference

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

Environment Used in this Article

  • RICOH THETA Z1 with firmware 2.01.0
  • gphoto2 2.5.28
  • MacOS Monterey 12.3
  • Apple M1 chip

I tested running USB API commands from my Mac laptop to control my THETA Z1 following the steps @craig laid out in this blog post.

I’m assuming that most developers would want to use the THETA USB API from Linux on a Jetson or Raspberry Pi. But to test the USB API easily, running it on my MacBook Air is handy.

  1. Checked if gphoto2 was already installed. No.
  2. Ran brew install gphoto2
  3. Waited a while for Updating Homebrew... Probably 5 minutes. It was successfully installed. Here’s part of the output confirming that it was installed:
==> Checking for dependents of upgraded formulae...
==> No broken dependents found!
==> Caveats
==> python@3.8
Python has been installed as
  /usr/local/opt/python@3.8/bin/python3

Unversioned symlinks `python`, `python-config`, `pip` etc. pointing to
`python3`, `python3-config`, `pip3` etc., respectively, have been installed into
  /usr/local/opt/python@3.8/libexec/bin

You can install Python packages with
  /usr/local/opt/python@3.8/bin/pip3 install <package>
They will install into the site-package directory
  /usr/local/lib/python3.8/site-packages

See: https://docs.brew.sh/Homebrew-and-Python

python@3.8 is keg-only, which means it was not symlinked into /usr/local,
because this is an alternate version of another formula.

If you need to have python@3.8 first in your PATH, run:
  echo 'export PATH="/usr/local/opt/python@3.8/bin:$PATH"' >> /Users/jcasman/.bash_profile

For compilers to find python@3.8 you may need to set:
  export LDFLAGS="-L/usr/local/opt/python@3.8/lib"

For pkg-config to find python@3.8 you may need to set:
  export PKG_CONFIG_PATH="/usr/local/opt/python@3.8/lib/pkgconfig"

==> gstreamer
Consider also installing gst-plugins-base and gst-plugins-good.

The gst-plugins-* packages contain gstreamer-video-1.0, gstreamer-audio-1.0,
and other components needed by most gstreamer applications.

My Z1 was connected to my MacBook Air with a USB-C to USB-C cable.

  1. Ran gphoto2 with no command to see options
MacBook-Air:RICOH jcasman$ gphoto2
Usage: gphoto2 [-?qvalLnPTDR] [-?|--help] [--usage] [--debug]
        [--debug-loglevel=STRING] [--debug-logfile=FILENAME] [-q|--quiet]
        [--parsable] [--hook-script=FILENAME] [--stdout] [--stdout-size]
        [--auto-detect] [--show-exif=STRING] [--show-info=STRING]
        [--summary] [--manual] [--about] [--storage-info] [--shell]
        [-v|--version] [--list-cameras] [--list-ports] [-a|--abilities]
        [--port=FILENAME] [--speed=SPEED] [--camera=MODEL] [--usbid=USBIDs]
        [--list-config] [--list-all-config] [--get-config=STRING]
        [--set-config=STRING] [--set-config-index=STRING]
        [--set-config-value=STRING] [--reset] [--keep] [--keep-raw]
        [--no-keep] [--wait-event=EVENT] [--wait-event-and-download=EVENT]
        [--capture-preview] [--show-preview] [-B|--bulb=SECONDS]
        [-F|--frames=COUNT] [-I|--interval=SECONDS] [--reset-interval]
        [--capture-image] [--trigger-capture] [--capture-image-and-download]
        [--capture-movie=COUNT or SECONDS] [--capture-sound]
        [--capture-tethered=EVENT] [-l|--list-folders] [-L|--list-files]
        [-m|--mkdir=DIRNAME] [-r|--rmdir=DIRNAME] [-n|--num-files]
        [-p|--get-file=RANGE] [-P|--get-all-files] [-t|--get-thumbnail=RANGE]
        [-T|--get-all-thumbnails] [--get-metadata=RANGE] [--get-all-metadata]
        [--upload-metadata=STRING] [--get-raw-data=RANGE]
        [--get-all-raw-data] [--get-audio-data=RANGE] [--get-all-audio-data]
        [-d|--delete-file=RANGE] [-D|--delete-all-files]
        [-u|--upload-file=FILENAME] [--filename=FILENAME_PATTERN]
        [--filenumber=NUMBER] [-f|--folder=FOLDER] [-R|--recurse]
        [--no-recurse] [--new] [--force-overwrite] [--skip-existing]
  1. Ran gphoto2 --summary
MacBook-Air:RICOH jcasman$ gphoto2 --summary
Camera summary:                                                                
Manufacturer: Ricoh Company, Ltd.
Model: RICOH THETA Z1
  Version: 2.00.1
  Serial Number: 10010097
Vendor Extension ID: 0x6 (1.10)
Vendor Extension Description: 

Capture Formats: 
Display Formats: Association/Directory, JPEG, MP4, DNG, Firmware
Supported MTP Object Properties:
	Association/Directory/3001: dc01/StorageID dc02/ObjectFormat dc04/ObjectSize dc0b/ParentObject dc41/PersistantUniqueObjectIdentifier dc44/Name
	JPEG/3801: dc01/StorageID dc02/ObjectFormat dc03/ProtectionStatus dc04/ObjectSize dc07/ObjectFileName dc08/DateCreated dc09/DateModified dc0b/ParentObject dc41/PersistantUniqueObjectIdentifier dc44/Name dc87/Width dc88/Height
	MP4/b982: dc01/StorageID dc02/ObjectFormat dc03/ProtectionStatus dc04/ObjectSize dc07/ObjectFileName dc08/DateCreated dc09/DateModified dc0b/ParentObject dc41/PersistantUniqueObjectIdentifier dc44/Name dc87/Width dc88/Height
	DNG/3811: dc01/StorageID dc02/ObjectFormat dc03/ProtectionStatus dc04/ObjectSize dc07/ObjectFileName dc08/DateCreated dc09/DateModified dc0b/ParentObject dc41/PersistantUniqueObjectIdentifier dc44/Name dc87/Width dc88/Height
	Firmware/b802: dc01/StorageID dc02/ObjectFormat dc04/ObjectSize dc0b/ParentObject dc41/PersistantUniqueObjectIdentifier dc44/Name

Device Capabilities:
	File Download, File Deletion, No File Upload
	Generic Image Capture, Open Capture, No vendor specific capture

[truncated]

  1. Listed files on my THETA Z1
MacBook-Air:RICOH jcasman$ gphoto2 --list-files
There is no file in folder '/'.                                                
There is no file in folder '/store_00020001'.
There is no file in folder '/store_00020001/DCIM'.
There are 7 files in folder '/store_00020001/DCIM/100RICOH'.
#1     R0011873.MP4               rd 20394 KB 3840x1920 video/mp4 1546342456
#2     R0011874.MP4               rd 15603 KB 3840x1920 video/mp4 1546342597
#3     R0011875.MP4               rd 216506 KB 3840x1920 video/mp4 1546364016
#4     R0011876.JPG               rd  8280 KB 6720x3360 image/jpeg 1546366110
#5     R0011877.JPG               rd  8258 KB 6720x3360 image/jpeg 1546333811
#6     R0011878.JPG               rd  8228 KB 6720x3360 image/jpeg 1546333828
#7     R0011879.JPG               rd  8687 KB 6720x3360 image/jpeg 1546329847
  1. Set the shutter audio volume, which supports values 0 to 100. First check to see current setting. It’s 30.
MacBook-Air:RICOH jcasman$ gphoto2 --get-config=502c

Label: Audio Volume

Readonly: 0

Type: MENU

Current: 30
Choice: 0 0
Choice: 1 1
Choice: 2 2
Choice: 3 3
Choice: 4 4
Choice: 5 5
Choice: 6 6

...

Choice: 97 97
Choice: 98 98
Choice: 99 99
Choice: 100 100
END
  1. Setting shutter volume to 30, 60 and 100 and taking pictures to check volume level. I can definitely hear the difference.
MacBook-Air:RICOH jcasman$ gphoto2 --set-config=502c=30
MacBook-Air:RICOH jcasman$ gphoto2 --capture-image
New file is in location /store_00020001/DCIM/100RICOH/R0011880.JPG on the camera
MacBook-Air:RICOH jcasman$ gphoto2 --set-config=502c=60
MacBook-Air:RICOH jcasman$ gphoto2 --capture-image                        
New file is in location /store_00020001/DCIM/100RICOH/R0011881.JPG on the camera
MacBook-Air:RICOH jcasman$ gphoto2 --set-config=502c=100
MacBook-Air:RICOH jcasman$ gphoto2 --capture-image                       
New file is in location /store_00020001/DCIM/100RICOH/R0011882.JPG on the camera
  1. Getting a specific file. Listing files first. Downloading file #10 to my MacBook Air
MacBook-Air:RICOH jcasman$ gphoto2 --list-files
There is no file in folder '/'.                                                
There is no file in folder '/store_00020001'.
There is no file in folder '/store_00020001/DCIM'.
There are 10 files in folder '/store_00020001/DCIM/100RICOH'.
#1     R0011873.MP4               rd 20394 KB 3840x1920 video/mp4 1546342456
#2     R0011874.MP4               rd 15603 KB 3840x1920 video/mp4 1546342597
#3     R0011875.MP4               rd 216506 KB 3840x1920 video/mp4 1546364016
#4     R0011876.JPG               rd  8280 KB 6720x3360 image/jpeg 1546366110
#5     R0011877.JPG               rd  8258 KB 6720x3360 image/jpeg 1546333811
#6     R0011878.JPG               rd  8228 KB 6720x3360 image/jpeg 1546333828
#7     R0011879.JPG               rd  8687 KB 6720x3360 image/jpeg 1546329847
#8     R0011880.JPG               rd  7759 KB 6720x3360 image/jpeg 1652657054
#9     R0011881.JPG               rd  7776 KB 6720x3360 image/jpeg 1652657080
#10    R0011882.JPG               rd  7761 KB 6720x3360 image/jpeg 1652657098
MacBook-Air:RICOH jcasman$ gphoto2 --get-file 10
Saving file as R0011882.JPG

  1. Checking the file info. In this case, it’s a 360 video.
MacBook-Air:RICOH jcasman$ gphoto2 --show-info 1
Information on file 'R0011873.MP4' (folder '/store_00020001/DCIM/100RICOH'):   
File:
  Mime type:   'video/mp4'
  Size:        20883105 byte(s)
  Width:       3840 pixel(s)
  Height:      1920 pixel(s)
  Permissions: read/delete
  Time:        Tue Jan  1 03:34:16 2019
Thumbnail:
  Mime type:   'image/jpeg'
  Size:        20710 byte(s)
  Width:       640 pixel(s)
  Height:      320 pixel(s)
Audio data:
  None available.
  1. Checking battery level, balance, capture mode
MacBook-Air:RICOH jcasman$ gphoto2 --get-config=batterylevel
Label: Battery Level                                                           
Readonly: 1
Type: TEXT
Current: 100%
END
MacBook-Air:RICOH jcasman$ gphoto2 --get-config=whitebalance
Label: WhiteBalance                                                            
Readonly: 0
Type: RADIO
Current: Automatic
Choice: 0 Automatic
Choice: 1 Daylight
Choice: 2 Unknown value 8001
Choice: 3 Unknown value 8002
Choice: 4 Tungsten
Choice: 5 Unknown value 8020
Choice: 6 Unknown value 8003
Choice: 7 Unknown value 8004
Choice: 8 Unknown value 8005
Choice: 9 Unknown value 8006
Choice: 10 Unknown value 8007
END
MacBook-Air:RICOH jcasman$ gphoto2 --get-config=capturemode
Label: Still Capture Mode                                                      
Readonly: 0
Type: RADIO
Current: Single Shot
Choice: 0 Single Shot
Choice: 1 Timelapse
Choice: 2 Unknown value 8002
Choice: 3 Unknown value 8003
Choice: 4 Unknown value 8004
Choice: 5 Unknown value 8005
Choice: 6 Unknown value 8006
Choice: 7 Unknown value 8007
END

Summary: Installing Homebrew on the Mac in order to install ggphoto2 was straightforward. It’s great to be able to attach my Z1 directly to my MacBook Air and test the USB API. I have not installed the alternative to gphoto2, libptp2, yet.

1 Like

Nice! Great that you got it working on the MacBook Air. Congratulations!

Once you get libptp installed, you can try ptpcam to set individual properties. I’m actually not sure how to do this gphoto2.

ptpcam --set-property=0xD801 --val="23.532000,23.532000+999.00m@20210904T170429.0+0900,WGS84"
1 Like

OK, I followed through the second half of the blog post for using ptplib2 on a Mac.

I download MacPorts and ran ptplib2 on my MacBook Air. I’d say it’s as easy as ggphoto2, though the important difference is being able to set GPS with libptp2.

I also had one small problem, not really anything to do with libptp2. After installing libptp2, I had to set the path correctly to run the port command. Not a big deal.

I’m running Big Sur

Downloaded the package for MacPorts, installed successfully

It looked good, but then I tried to run sudo port install libptp2

Got command not found.

Just need to set the path. Did sudo vi /etc/paths and added /opt/local/bin and /opt/local/sbin

Restarted terminal, it works!

MacBook-Air:~ jcasman$ port
MacPorts 2.7.2
Entering shell mode... ("help" for help, "quit" to quit)
[Users/jcasman] > quit
Goodbye

Checked camera information

MacBook-Air:~ jcasman$ ptpcam --info

Camera information
==================
Model: RICOH THETA Z1
  manufacturer: Ricoh Company, Ltd.
  serial number: '10010097'
  device version: 2.00.1
  extension ID: 0x00000006
  extension description: (null)
  extension version: 0x006e

Listing files

MacBook-Air:~ jcasman$ ptpcam --list-files

Listing files...
Camera: RICOH THETA Z1
Handler:           Size: 	Captured:      	name:
0x00000b5b:     20883105	2019-01-01 11:34	R0011873.MP4
0x00000b5c:     15976697	2019-01-01 11:36	R0011874.MP4
0x00000b5d:    221701512	2019-01-01 17:33	R0011875.MP4
0x00000b5e:      8478636	2019-01-01 18:08	R0011876.JPG
0x00000b61:      8455422	2019-01-01 09:10	R0011877.JPG
0x00000b62:      8425437	2019-01-01 09:10	R0011878.JPG
0x00000b6c:      8895100	2019-01-01 08:04	R0011879.JPG
0x00000b70:      7944650	2022-05-16 00:24	R0011880.JPG
0x00000b71:      7962563	2022-05-16 00:24	R0011881.JPG
0x00000b72:      7947196	2022-05-16 00:24	R0011882.JPG

Checked to see if there was GPS info set, tested setting the GPS info, checked to see that it was set

MacBook-Air:~ jcasman$ ptpcam --show-property=0xd801

Camera: RICOH THETA Z1
'UNKNOWN' is set to: "(null)"

MacBook-Air:~ jcasman$ ptpcam --set-property=0xD801 --val="23.532000,23.532000+999.00m@20210904T170429.0+0900,WGS84"

Camera: RICOH THETA Z1
'UNKNOWN' is set to: "(null)"
Changing property value to 23.532000,23.532000+999.00m@20210904T170429.0+0900,WGS84 [(null)] succeeded.

MacBook-Air:~ jcasman$ ptpcam --show-property=0xd801

Camera: RICOH THETA Z1
'UNKNOWN' is set to: "23.532000,23.532000+999.00m@20210904T080429,WGS84"

Summary: No real problems installing libptp2 and controlling my Z1 over a USB cable. Very easy to test the USB API on my MacBook Air.

1 Like

Congratulations! Nice job.

if you do

cd
cat .zprofile

can you show the output?

Didn’t macports add in the proper path?

you can run it after installing macports with source .zprofile

version of libptp2

Unfortunately, MacPorts seems to have installed an older version of libptp2, v 1.1.10.

The most recent version is 1.2.0

There may be some issues running the raw ptp commands to start/stop video. However, the settings should work.

Currently, the main limitation on the Mac would be starting and stopping the video.

This is how it works on a Jetson nano, but I couldn’t get the video start and stop to work on the Mac.