January 10, 2017 | Author: Marian Le Calvez | Category: N/A
Download Open Spherical Camera API Version 1.1.2...
OPEN SPHERICAL CAMERA v1.1.2 20/07/2016
SUMMARY MANUFACTURER GUIDE Introduction & Feedback Overview Discovery OSC Protocol a. info b. state c. commands Error Handling API SPECIFICATION Overview Commands I. System & Connection a. camera.startSession b. camera.closeSession c. camera.updateSession d. camera.wifiMode II. Recording & Shooting a. camera.takePicture b. camera._startRecording c. camera._stopRecording d. paramState III. Navigate & Get Information a. camera._getAttributes b. camera._listDirectory c. camera._getStreamUrl IV. Read, Edit & Delete a. camera._readFile b. camera._writeFile (unactive) c. camera.delete V. Metadata Commands a. camera.getMetadata b. camera._setMetadata c. camera._patchMetadata VI. Image Commands a. camera.getImage b. camera._getImagePreview c. camera.listImages VII. Get & Set Options a. camera.getOptions Giroptic 360cam OSC 1
b. camera.setOptions c. Options d. Appendix Revision History
Giroptic 360cam OSC 2
MANUFACTURER GUIDE
Giroptic 360cam OSC 3
Introduction & Feedback Welcome to the Giroptic Open Spherical Camera API. Your feedback helps us shape the development of the API. This preview includes the Manufacturer Guide and API Specification. Download PDFs of the latest revision of both documents at the links below: http://dev.360.tv/ We look forward to hearing your feedback on how we can improve the OSC API Specification and Manufacturer Guide. Whether you've encountered engineering pain points, confusing documentation, or unexpected behavior, please let us know. Send any questions or comments you may have to
[email protected]
Overview This guide provides spherical camera API implementation guidance to manufacturers of cameras with built in wifi. Please refer to OSC API Specification for the full set of commands.
Giroptic 360cam OSC 4
Discovery Discovery flow works as follows: the camera brings up a password protected WiFi network to signal its existence, the client can scan for such networks, display them to the user, and allow the user to connect to the right one by entering the correct password at least once. It consists of two parts for the camera implementation: defining a specific SSID to allow clients to find and connect to the right password protected network, and using default port 80 for HTTP. SSID and password SSID format: [Camera name].OSC The wifi SSID shall start with a human readable name (up to 20 characters), following by delimiter ‘.’ and “OSC” (OSC stands for “Open Spherical Camera”, the protocol used for communications between clients and cameras). The camera name contains manufacturer selected user friendly name. It is HIGHLY RECOMMENDED to add some entropy to the end of the name to prevent name collisions. For example, “VendorCamera123.OSC”, where “123” is used to differentiate between the same type of cameras nearby. The wifi MUST be protected with WPA2 PSK. The wifi password MUST be at least 8 characters long and it can contain letters, numbers, symbols, but no spaces. It can be changed only when the camera is connected to the phone. Once it is changed, the camera will be disconnected and needs to be reconnected using the new password. The camera MUST provide a reset mechanism in case the password is forgotten, e.g. a reset button in the camera to restore the default password. IP address and port: The camera’s IP address can be obtained from the wifi connection on the client side. For port, please use default port 80 for HTTP (port for update can be obtained from endpoints in /osc/info).
Giroptic 360cam OSC 5
OSC Protocol After the camera has been discovered, communication between the client and the camera is directly over the local network. All the following APIs are HTTP 1.1 based. API requests may be GET or POST requests. Basically, the camera needs to implement a HTTP server for OSC protocol.
Giroptic 360cam OSC 6
a. info Description The /osc/info API returns basic information about the camera and functionality it supports.
Input No input.
Output Name
Type
Description
manufacturer
String
The camera manufacturer.
model
String
The camera model.
description
String
Description of the camera model.
serialNumber
String
Serial number.
firmwareVersion
String
Current firmware version.
hardwareVersion
String
Current hardware version.
supportUrl
String
URL for the camera’s support webpage.
gps
Boolean
True if the camera has GPS.
gyro
Boolean
True if the camera has gyroscope.
uptime
Integer
Number of seconds since the camera boot.
api
String Array List of supported APIs.
endpoints
Object
_vendorSpecific
[type] (optional)
Details about the camera’s endpoints described below. Vendor specific additional info about the camera.
endpoints : is a JSON object containing information about the camera’s endpoints.
Name
Type
Description
httpPort
Integer
Port for HTTP server. (Default 80)
httpUpdatesPort
Integer
Port to receive updates over HTTP.
httpsPort (Optional)
Integer
Port for HTTPs server. (Default 443)
Giroptic 360cam OSC 7
httpsUpdatesPort (Optional)
Integer
Port to receive updates over HTTPs.
Errors No errors
Input & Output Example Request Input
Output Response { " manufacturer ": "XXXX", " model ": "XXXX", " description ": "XXXX", " serialNumber ": "XXXX", " firmwareVersion ": "XXXX", " hardwareVersion ": "XXXX", " supportUrl ": "XXXX", " gps ": XXXX, " gyro ": XXXX, " uptime ": XX, " api ": [ "/osc/info", "/osc/state", "/osc/checkForUpdates", "/osc/commands/execute", "/osc/commands/status" ], " endpoints ": { " httpPort ": XX, " httpUpdatesPort ": XX, }, }
cURL Example curl X GET H "contenttype: application/json" http://192.168.1.168/osc/info
Giroptic 360cam OSC 8
b. state Description The /osc/state API returns state of the camera. The difference between this and the info API is that the state contains mutable parameters that we’d like to be notified about the camera, (e.g. battery level), while the info only contains static attributes of the camera (e.g. manufacturer or attributes that don’t change often like firmware version).
Input No input.
Output Name
Type
Description
fingerprint
String
Fingerprint (unique identifier) of the current camera state.
state
Object
State description of the camera according to the state specification below.
state: is a JSON object containing information about the camera state.
Name
Type
Description
sessionId
String
ID of the current session. Only available if a session is start.
sessionTimeout
Integer
Remaining time of the current session.
_cameraState
String
Current state of the camera e.g. "recording " "idle " "busy " "setting" or "error ".
batteryLevel
Number
Expressed as an integer point value of the battery remaining, e.g. 75 (out of 100).
storageChanged
Boolean
True if a new type of storage (e.g. a SD card or a USB drive) is inserted/removed. (needed for Google OSC, always flase for us)
TotalSpace
Integer
Total available space in bytes on SD card
remainingSpace
Integer
Remaining space in bytes on SD card
remainingPictures
Integer
Remaining pictures count available to capture for image/burst/timelapse modes
remainingVideo
Integer
Remaining record time available in seconds for video mode Giroptic 360cam OSC 9
_vendorSpecific
[type] (optional)
Vendor specific additional state about the camera.
Errors No errors
Example Input Request
Output Response { " fingerprint ": "XXXXXX", " state ": { " sessionId ": "XXXXXX", " sessionTimeout ": XX, " sessionExclusive ": XXXX, " _cameraState ": "XXXX ", " batteryLevel ": XX, " totalSpace ": XX, " remaining Space ": XX, ... } }
cURL Example curl X GET H "contenttype: application/json" http://192.168.1.168/osc/state
Giroptic 360cam OSC 10
c. commands Description The commands API executes specified commands on the camera and checks the status (in progress, done etc.) of executed commands. All commands need to be implemented based on the specification in the OSC API Specification. Note: ● After a command returns state done and results, or error state, the camera may forget about command ID. ● Response to command “camera.getImage” needs to be “Content Type: image/jpeg” when the state is done.
Execute The /osc/commands/execute API executes specified commands on the camera. The output is a command object.
Input Name
Type
Description
name
String
Name of the command to be executed.
parameters
Object
Command input parameters according to the command definitions specification. Please refer to “OSC API Specification” for examples.
Name
Type
Description
name
String
Name of the command (same as in input).
state
String
State of the command. Could be one of the following: ● " done " command is complete, results has been returned in this response ● " inProgress " command execution is still in progress ● " error " command has failed, see error in the response
id (Optional)
String
Command ID. This value is required for commands returning states inProgress. For example, the takePicture command takes a few seconds due to the need for stitching.
Output
Giroptic 360cam OSC 11
results (Optional)
Object
Command results. This value is required for commands returning state done if the command is expected to return any results, e.g. “ results ” : { “ AAA ”: “BBB”, ... }. Please refer to “OSC API Specification” for examples.
error (Optional)
Object
Command error description. This value is required for commands returning state error, e.g. “ error ”: { “ code ”: “badSessionId” }
progress (Optional)
Object
Command progress description. This value is required for commands returning state inProgress, e.g. “progress”: { “ completion ”: X.X }
Errors Error Code unknownCommand cameraInExclusiveUse missingParameter
Description Command executed is unknown. Camera is already in exclusive use, new session can’t be started. Any required parameter is not specified.
invalidParameterName
Any input parameter or option name is unrecognized or supported.
invalidParameterValue
Any input parameter or option name is recognized, but its value is invalid for various reasons, for example, the sessionId doesn't exist or it is not active any more or its type is incorrect or the continuationToken is out of range or the option value is incorrect.
Giroptic 360cam OSC 12
Input & Output Example Input Request { " parameters " :{ " sessionId ": "XXXXXX", " timeout " : XX } }
Output Response { " results " :{ " sessionId ": "XXXXXX", " timeout ": XX } }
Error Output { " error ":{ " code ": "invalidParameterName", " message ": "parameter sessionId is missing" } }
cURL Example curl X POST H "contenttype: application/json" http://192.168.1.168/osc/commands/execute d '{"name": "camera.updateSession", "parameters": {"sessionId": "XXXXXXXXXX", "timeout": XX}}'
Giroptic 360cam OSC 13
Error Handling Please use the "200 OK" status code for all errors defined in this specification. For all other errors, the choice of status code (e.g. 400 or 500) is at the discretion of the manufacturer. The response should always include a JSON body in the following format for ANY error case: { " name ": "camera.info", " state ": "error", " error ": { " code ": "serverError", " message ": "cannot get camera info." } } “name” can be any of “camera.info”, “camera.state”, “camera.checkForUpdates”, “camera.commands.status” and “camera.commandName”. “code” should be “serverError” for 5XX status code, “clientError” for 4XX status code and any of the three (missingParameter, invalidParameterName and invalidParameterValue) for 200 status code. “message” is defined by manufacturers and is not expected to be a localized message.
Giroptic 360cam OSC 14
API SPECIFICATION
Giroptic 360cam OSC 15
Overview This document describes a proposed set of commands for a variety of oneclick spherical cameras (with builtin wifi). The goal is to allow any app on any camera (current target is Android) to control any connected spherical camera which implements this API.
Commands Commands input/output are in JSON format and part of HTTP request/response respectively. Please refer to Open Spherical Camera API Manufacturer Guide for more complete examples.
Giroptic 360cam OSC 16
I. System & Connection
Giroptic 360cam OSC 17
a. camera.startSession Description Starts a session that times out after a fixed interval. Locks the camera to the requesting client, and makes sure the camera stay awake.
Command Parameters Parameters timeout (optional)
Type int
Description
Possible Input
Requested session timeout in seconds. If not omitted, the server is responsible for determining a reasonable timeout.
[0 ; + ∞ ]
Results Results
Errors
sessionId : Unique identifier to be used for this cameraInExclusiveUse : camera is already in session. exclusive use, new session can’t be started.
timeout :Responded session timeout in invalidParameterName : any input parameter seconds. is unrecognized.
invalidParameterValue : any input parameter is recognized, but its value is invalid for various reasons, e.g. it is out of range or its type is incorrect.
Input & Output Command Input { " parameters " :{ " timeout " : XX } }
Command Output { " results " :{ " sessionId ": "XXXXX", " timeout ": XX } }
Output Error { " error ":{ " code ": "cameraInExclusiveUse", " message ": "camera already in exclusive use" } }
cURL Example curl X POST H "contenttype: application/json" http://192.168.1.168/osc/commands/execute d '{"name": "camera.startSession", "parameters": {"timeout": XX}}' Giroptic 360cam OSC 18
b. camera.closeSession Description Disconnects from camera .
Command Parameters Parameters sessionId
Type
Description
String
Possible Input
Unique session identifier obtained from the camera.startSession command.
Composed by 10 characters.
Results Results
Errors
This command returns no result.
missingParameter : any required parameter is not specified, e.g. sessionId is not specified.
invalidParameterName : any input parameter is unrecognized.
invalidParameterValue : any input parameter is recognized, but its value is invalid for various reasons, for example, the sessionId doesn't exist or it is not active any more or its type is incorrect.
Input & Output Command Input { " parameters " :{ " sessionId ": "XXXXXX" } }
Command Output
Output Error { " error ":{ " code ": "invalidParameterValue", " message ": "parameter sessionId is incorrect type" } }
cURL Example curl X POST H "contenttype: application/json" http://192.168.1.168/osc/commands/execute d '{"name": "camera.closeSession", "parameters": {"sessionId": "XXXXXXXXXX"}}' Giroptic 360cam OSC 19
c. camera.updateSession Description Refreshes the session timeout.
Command Parameters Parameters
Type
sessionId
String
timeout (optional)
int
Description
Possible Input
Unique session identifier.
Composed by 10 characters.
Requested session timeout in seconds. If it is omitted (HTTP request has no body), the server is responsible for determining a reasonable timeout.
[0 ; + ∞ ]
Results Results
Errors
sessionId : Unique identifier to be used for this missingParameter : any required parameter is session. not specified, e.g. sessionId is not specified.
timeout :Responded session timeout in invalidParameterName : any input parameter seconds. is unrecognized.
invalidParameterValue : any input parameter is recognized, but its value is invalid for various reasons, for example, the sessionId doesn't exist or it is not active any more or its type is incorrect.
Input & Output Command Input { " parameters " :{ " sessionId ": "XXXXXX", " timeout " : XX } }
Command Output { " results " :{ " sessionId ": "XXXXXX", " timeout ": XX } }
Output Error { " error ":{ " code ": "invalidParameterName", " message ": "parameter sessionId is missing" } } Giroptic 360cam OSC 20
cURL Example curl X POST H "contenttype: application/json" http://192.168.1.168/osc/commands/execute d '{"name": "camera.updateSession", "parameters": {"sessionId": "XXXXXXXXXX", "timeout": XX}}'
Giroptic 360cam OSC 21
d. camera.wifiMode Description Sets the wifi mode of the camera. Options are APP mode, LAN mode, or OFF. Before changing the mode, current session is closed. If the requested mode correspond to the wifi mode configured on the camera, nothing happen.
Command Parameters Parameters
Type
Description
Possible Input
sessionId
String
Unique session indentifier obtained from the camera.startSession command.
mode
String
Requested wifi mode
Composed by 10 characters “LAN”: Station mode “direct”: Access Point mode “OFF”: wifi off
Results Results
Errors
This command return no result.
invalidParameterName : any input parameter is unrecognized.
invalidParameterValue : any input parameter is recognized, but its value is invalid for various reasons, e.g. it is out of range or its type is incorrect.
invalidOperation : wifiMode command isn’t available when camera is on PoE mode
Input & Output Command Input { " parameters " :{ " sessionId ": "XXXXX", " mode ": “XXXXX” } }
Command Output
Output Error { " error ":{ " code ": "invalidParameterName", " message ": "parameter sessionId is missing" } } Giroptic 360cam OSC 22
cURL Example curl X POST H "contenttype: application/json" http://192.168.1.168/osc/commands/execute d '{"name": "camera.wifiMode", "parameters": {"sessionId": "XXXXXXXXXX", "mode": "LAN"}}'
Giroptic 360cam OSC 23
II. Recording & Shooting
Giroptic 360cam OSC 24
a. camera.takePicture Description Captures equirectangular images when the captureMode option is specified as “image” or “_burst”, saving lat/long coordinates to EXIF (if your camera GPS is enabled).
Command Parameters Parameters sessionId
Type String
Description
Possible Input
Unique session identifier obtained from the camera.startSession command.
Composed by 10 characters.
Results Results
Errors
fileUri: URL of the picture taken.
missingParameter : any required parameter is not specified, e.g. sessionId is not specified.
invalidParameterName : any input parameter is unrecognized.
invalidParameterValue : any input parameter is recognized, but its value is invalid for various reasons, for example, the sessionId doesn't exist or it is not active any more or its type is incorrect.
Input & Output Command Input { " parameters " :{ " sessionId ": "XXXXXX" } }
Command Output { " results " :{ " fileUri ": "file URI" } }
Output Error { " error ":{ " code ": "invalidParameterValue", " message ": "not available on this captureMode" } }
cURL Example curl X POST H "contenttype: application/json" http://192.168.1.168/osc/commands/execute d '{"name": "camera.takePicture", "parameters": {"sessionId": "XXXXXXXXXX"}}' Giroptic 360cam OSC 25
b. camera._startRecording Description Starts recording video when the captureMode option is specified as “_video”. When the camera captureMode has been set to “_timelapse”, begins capturing pictures.
Command Parameters Parameters sessionId
Type
Description
String
Possible Input
Unique session identifier obtained from the camera.startSession command.
Composed by 10 characters.
Results Results
Errors
This command returns no result.
missingParameter : any required parameter is not specified, e.g. sessionId is not specified.
invalidParameterName : any input parameter is unrecognized.
invalidParameterValue : any input parameter is recognized, but its value is invalid for various reasons, for example, the sessionId doesn't exist or it is not active any more or its type is incorrect.
Input & Output Command Input { " parameters " :{ " sessionId ": "XXXXXX" } }
Command Output
Output Error { " error ":{ " code ": "invalidParameterValue", " message ": "sessionId type is invalid" } }
Giroptic 360cam OSC 26
cURL Example curl X POST H "contenttype: application/json" http://192.168.1.168/osc/commands/execute d '{"name": "camera._startRecording", "parameters": {"sessionId": "XXXXXXXXXX"}}'
Giroptic 360cam OSC 27
c. camera._stopRecording Description Ends recording video when the captureMode option is specified as “_video”. When the camera captureMode has been set to “_timelapse”, ends capturing pictures.
Command Parameters Parameters sessionId
Type
Description
String
Possible Input
Unique session identifier obtained from the camera.startSession command.
Composed by 10 characters.
Results Results
Errors
fileUri: URI of recorded video or the picture missingParameter : any required parameter is taken. not specified, e.g. sessionId is not specified.
invalidParameterName : any input parameter is unrecognized.
invalidParameterValue : any input parameter is recognized, but its value is invalid for various reasons, for example, the sessionId doesn't exist or it is not active any more or its type is incorrect.
Input & Output Command Input { " parameters " :{ " sessionId ": "XXXXXX" } }
Command Output { " results " :{ } }
" fileUri ": "file URI"
Output Error { " error ":{ " code ": "invalidParameterValue", " message ": "Camera is busy" } }
Giroptic 360cam OSC 28
cURL Example curl X POST H "contenttype: application/json" http://192.168.1.168/osc/commands/execute d '{"name": "camera._stopRecording", "parameters": {"sessionId": "XXXXXXXXXX"}}'
Giroptic 360cam OSC 29
d. paramState Description This is the camera server push command. Using this technique the connection is held opened and new pieces of information can be pushed over that existing connection, from server to client, without the connection being closed and reopened as it is with “HTTP LongPolling”. The client can then refresh information whenever there is a change on the server.
Input No input Output
Name
Type
Description
recordStatus
boolean
Indicates if the camera is in recording/take picture state.
timelapseRecorded Pictures
number
On timelapse mode, the camera returns the number of recorded pictures.
convStatus
boolean
Indicates if the camera AE/AWB convergence flag is done and then ready to record picture.
alertBatteryLevel
boolean
Indicates that the camera is in low battery level (level
