Categories
USB API Z1

MACOS and RICOH THETA USB API

Using gphoto2 to send USB API commands to a RICOH THETA Z1

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/

Using brew to install gphoto2
brew automatically installs required libraries and packages on Mac OS X

Basic gphoto2 commands

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

testing gphoto2 on Mac

Getting Summary Information on THETA Z1

On your Mac use gphoto2 --summary

List Files on THETA

gphoto2 --list-files

Set shutter volume

setting volume of shutter with USB API from Mac and checking configuration

Download Files from RICOH THETA To Your Mac

Get files 1-3 from Z1 on Mac

Viewing Images on Mac

Viewing the Z1 images on Mac OS X after downloading with the USB API

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.

Testing file dowloaded with gphoto2 using RICOH Basic app 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

When camera is in manual exposure program, you can set the ISO. In this example, ISO is set 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.

Downloading MacPorts
Installing MacPorts on MacOS Monterey
Successfully installed MacPorts
successfully installed libptp2 with MacPorts

Get Camera Info with ptpcam

Set GPS Information 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

Notable Replies

  1. 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.

  2. Avatar for craig craig says:

    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"
    
  3. 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.

  4. Avatar for craig craig says:

    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.

Continue the discussion at community.theta360.guide

Participants