Direct Upload via Street View

Version 2.1

Background

In earlier versions of the API, an OSC compliant camera would create a Wi-Fi access point that the Google Street View iOS and Android apps could connect to. The app would both direct the OSC camera to capture photos and also download the captured content from the camera to then publish it to Google Street View. To expedite the publication of content, we have introduced a new optional workflow that allows OSC cameras to upload content to the Street View server directly. This eliminates the lengthy double transfer of content first from the camera to the app and then from the app to the Street View server. This was added in API level 2.1 and is only relevant to OSC cameras that can both provide a Wi-Fi access point and also connect to an infrastructure Wi-Fi access point with access to the Internet.

Overview

The new upload workflow requires cameras to provide a way (e.g. a dedicated physical button or a combination of existing buttons) to allow users to switch between two Wi-Fi modes:

  • Direct mode: In this mode, the camera acts as an access point which allows a mobile device to connect to it. In this mode, mobile devices can control the camera to perform tasks such as capturing photos. Mobile devices can also provide the camera with Wi-Fi access point credentials that the camera can then use to switch to Internet mode.
  • Internet mode: In this mode, the camera connects to a Wi-Fi access point with Internet access. It will use the access point identifier and password that was provided to it from the app when the camera was previously in Direct mode. Mobile devices can initiate uploads from the camera directly to the Street View server in this mode. They can also continue to control the camera to perform tasks such as capturing photos.

The camera mode should persist across the camera being turned off and being turned back on again. Also, it is highly recommended that the camera offer a signal (e.g. light, sound or indicator on a screen) to inform users of the current Wi-Fi mode.

The camera should also have discovery protocols (see Discovery) implemented to handle communication while the camera is in Internet mode.

Internet Mode Setup

  1. The user turns on the camera. It starts in Direct mode since Internet mode is not yet set up.
  2. The mobile device connects to camera’s Wi-Fi.
  3. The app sends the switchWifi command to the camera with the SSID of the infrastructure Wi-Fi access point the camera will need to connect to, the password for that access point, and a secret key K that the camera uses to authenticate itself with the app during discovery.
    • Please note the camera should store both the Wi-Fi credential and the pre-shared K securely.
    • It is recommended that the camera store multiple Wi-Fi credentials since the camera may need to connect to different infrastructure Wi-Fi access points. The minimum requirement is for the camera to store the most recent Wi-Fi credential.
  4. The user can now switch between Internet and Direct modes directly from the camera, e.g. with a physical toggle button.

Discovery

Discovery for OSC cameras is a zeroconf based protocol. The camera MUST implement IPv4 Link-Local Addressing and MUST comply with the mDNS (Multicast DNS) and DNS-SD (DNS-Based Service Discovery) specifications:

Service Instance Names

For the <Service> portion of the Service Instance Name, OSC cameras should use _osc._tcp. For the <Domain> portion of the Service Instance Name, OSC cameras should use local.. Note that there is a trailing . after local.

TXT record

We require the camera to send the following key/value pairs in the TXT record: txtvers, ty, and id.

txtvers

To allow for updates to the TXT version in the future, use the key/value pair txtvers=1.

ty

Provides a user-readable name of the camera, e.g. ty=Google Street View Optimized Spherical Camera Model XYZ.

id

Provides a unique id of the camera, e.g. id=A unique id of the camera. The value for id MUST be the same as the cameraId in /osc/info output.

Announcements

On camera startup or shutdown, the camera MUST perform the announcement step as described in the mDNS specification. It SHOULD send the corresponding announcement at least twice with at least a one-second interval between them.

Startup

On camera startup it MUST perform probing and announcing steps as described in the mDNS specification. SRV, PTR and TXT records should be sent in this case. It is recommended to group all records into one DNS response if possible. If not, the following order is recommended: SRV, PTR, TXT records.

Shutdown

On camera shutdown it SHOULD try to notify all interested parties by sending a “goodbye packet” with TTL=0 as described in section 10.1 of the mDNS documentation.

TLS-PSK

The pre-shared secret key K in Internet Mode Setup can be used for the following purposes:

  • Authentication between the app and camera
  • Protecting data exchanged between the app and camera

Manufacturers MUST use ECDHE_PSK Cipher Suites for Transport Layer Security (TLS) and may use any library for this (e.g. mbedTLS).

New Upload Flow

  1. If the camera is not in Internet mode, the user switches it to Internet mode. The camera connects to the infrastructure Wi-Fi using stored credentials.
  2. The mobile device also connects to the infrastructure Wi-Fi and discovers the camera.
    • This requires the camera to implement a local discovery protocol mDNS/DNS-SD (see Discovery).
    • There is no specific requirement on how it is implemented (mDNSResponder is a good reference).
    • The app and the camera MUST implement TLS ECDHE_PSK (see TLS-PSK), using the pre-shared secret key K as the PSK.
    • After the camera has been discovered, client communication is enabled with it directly over the local network based on HTTP 1.1. Data formats are JSON based. Requests may be GET or POST requests.
  3. The app queries the camera for a list of files with the listFiles command.
  4. The app initiates upload with the uploadFile command to upload an image or video directly from the camera to the Street View server.
  5. The app polls the camera periodically for upload progress with the status command.

Send feedback about...

Open Spherical Camera API